Dotfiles Project Assistant

Expert assistant for working with mimikun's comprehensive cross-platform dotfiles repository. This skill provides guidance on managing dotfiles with chezmoi, mise task automation, aqua package management, and maintaining quality across Linux, Windows, and macOS environments.

What This Skill Does

This skill helps you work with a sophisticated dotfiles project that uses:

The skill understands cross-platform development patterns, OS-specific templating, secret management, and quality assurance workflows.

Project Structure

Configuration File Naming

Key Directories

Core Workflows

Working with chezmoi

1. **Before making changes:**

```bash

chezmoi status # View current status

chezmoi diff # Check differences

```

2. **Making changes:**

```bash

chezmoi edit <file> # Edit template files

chezmoi apply --verbose # Apply changes

```

3. **Re-initialization:**

```bash

chezmoi init --apply --verbose https://github.com/mimikun/dotfiles.git

```

Using mise Tasks

Always use mise for common operations:

```bash

mise tasks run lint # Run linting

mise tasks run format # Run formatting

mise tasks run clean # Clean temporary files

mise tasks run update # Update dependencies

mise tasks run patch:branch # Create patch branch

mise tasks list # View all available tasks

```

Managing Packages with aqua

```bash

aqua install # Install packages from aqua.yaml

aqua update # Update packages

aqua generate <package> # Add new package

aqua which <tool> # Verify package installation

```

Development Standards

Lua Development (Neovim)

Target: Lua 5.1 (Neovim compatibility)

**Plugin structure:**

```lua

return {

"plugin/name",

dependencies = {},

opts = {},

config = function(_, opts)

-- Configuration

end,

}

```

**Tools:**

Shell Scripting

**Bash scripts:**

```bash

#!/usr/bin/env bash

set -euo pipefail

{{- if eq .chezmoi.os "windows" }}

Windows-specific code

{{- else }}

Unix-specific code

{{- end }}

```

**PowerShell scripts:**

```powershell

#Requires -Version 5.1

[CmdletBinding()]

param()

Use PSScriptAnalyzer compliant code

```

chezmoi Templates

**OS detection patterns:**

```go-template

{{- $isWindows := (eq .chezmoi.os "windows") -}}

{{- $isLinux := (eq .chezmoi.os "linux") -}}

{{- $isMacOS := (eq .chezmoi.os "darwin") -}}

{{- $isWorkLinux := (and (eq .chezmoi.os "linux") (isExecutable "/usr/local/bin/this_is_work_pc")) -}}

{{- $isWorkWindows := (and (eq .chezmoi.os "windows") (isExecutable "C:\\Program Files\\Yt Env Checks\\this_is_work_pc.exe")) -}}

{{- $isWorkPC := (or $isWorkLinux $isWorkWindows) -}}

```

**Secret management:**

```go-template

{{- if $isWorkPC }}

{{- if $isWorkLinux }}

{{ (rbwFields "item-name").field_name.value }}

{{- else }}

{{ (bitwardenFields "item" "item-id").field_name.value }}

{{- end }}

{{- else }}

Personal PC: Use static values

{{- end }}

```

Quality Assurance

Running Quality Checks

```bash

Manual pre-commit hooks

lefthook run pre-commit

Individual checks

stylua --check . # Lua formatting

selene . # Lua linting

npx prettier --check . # JS/TS formatting

npx cspell "**/*.md" "**/*.txt" # Spell checking

pwsh -Command "Invoke-ScriptAnalyzer -Path . -Recurse" # PowerShell

Makefile shortcuts

make lint # Run all linting

make format # Run formatting

make test # Full test suite

```

Branch Management

```bash

make patch-branch # Create new patch branch

make switch-master # Switch to master

make delete-branch # Clean up branches

make morning-routine # Fetch, pull, cleanup

```

Instructions for AI Agent

When working with this dotfiles project:

1. **ALWAYS check file types before editing:**

- Look for `.tmpl` extension (requires chezmoi template syntax)

- Check for `dot_` prefix (becomes hidden file)

- Verify `executable_` or `private_` prefixes

2. **For template files:**

- Use appropriate OS detection patterns

- Handle secrets via Bitwarden CLI integration

- Test templates with `chezmoi execute-template < file`

- Preview changes with `chezmoi diff` before applying

3. **For Lua files (Neovim config):**

- Target Lua 5.1 compatibility

- Follow lazy.nvim plugin structure

- Format with stylua

- Lint with selene

4. **For shell scripts:**

- Use `set -euo pipefail` for bash

- Include `#Requires -Version 5.1` for PowerShell

- Follow PSScriptAnalyzer guidelines for PowerShell

- Handle cross-platform paths appropriately

5. **Quality assurance workflow:**

- Run `mise tasks run lint` before committing

- Use `lefthook run pre-commit` to validate changes

- Test on target OS when possible

- Run `chezmoi diff` to preview dotfile changes

6. **Multi-OS support:**

- Always use chezmoi variables for paths

- Test executable detection for work PC identification

- Use appropriate path separators per OS

- Handle OS-specific tool variations

7. **Commit message format:**

```

<type>(<scope>): <subject>

Types: feat, fix, docs, style, refactor, test, chore

```

8. **Never:**

- Hardcode paths (use chezmoi variables)

- Commit secrets (use template variables)

- Skip testing templates before applying

- Break shell startup performance

- Skip OS validation for cross-platform code

9. **Health checks:**

```bash

mise doctor # Check mise installation

aqua which <tool> # Verify aqua packages

chezmoi execute-template < file # Test templates

```

10. **Pro tips:**

- Use `chezmoi cd` to navigate to source directory

- Leverage mise tasks for complex operations

- Use aqua for consistent tool versions across environments

- Profile shell startup time for performance optimization

Examples

**Adding a new config file:**

```bash

For a hidden config file (.myconfig)

chezmoi add --template ~/.myconfig

Edit with proper template syntax

chezmoi edit ~/.myconfig

Apply changes

chezmoi diff

chezmoi apply --verbose

```

**Creating OS-specific configuration:**

```bash

Edit template file

chezmoi edit ~/.config/tool/config

Add OS detection

{{- if eq .chezmoi.os "linux" }}

linux_specific_config: true

{{- else if eq .chezmoi.os "darwin" }}

macos_specific_config: true

{{- else if eq .chezmoi.os "windows" }}

windows_specific_config: true

{{- end }}

```

**Running full quality check before commit:**

```bash

mise tasks run lint

mise tasks run format

lefthook run pre-commit

chezmoi diff

```

Constraints

Notes