diff --git a/.memory/decisions.md b/.memory/decisions.md new file mode 100644 index 0000000..5e5489f --- /dev/null +++ b/.memory/decisions.md @@ -0,0 +1,59 @@ +# Dotfiles Decisions + +## Desktop Environment: Hyprland + Wayland + +- **Decision:** Hyprland as primary compositor, full Wayland stack +- **Rationale:** Modern Wayland compositor with tiling, animations, and good HiDPI support +- **Constraints:** XWayland needed for legacy apps; special window rule to suppress maximize events +- **Input:** Caps Lock remapped to Super (`caps:super`), `alts_toggle` for US/BR layout switching + +## Shell: Fish (not Bash/Zsh) + +- **Decision:** Fish as primary interactive shell; bash/zsh configs retained for compatibility +- **Rationale:** Better autocompletion, syntax highlighting, friendly defaults +- **Plugin manager:** fisher (minimal, text-file-based) +- **No `oh-my-fish`** — prefer minimal plugin set (just catppuccin theme) + +## Theme: Catppuccin Mocha (global) + +- **Decision:** Single colorscheme (Catppuccin Mocha) applied uniformly across all tools +- **Rationale:** Consistent visual identity; official plugins available for Fish, Neovim, Kitty +- **Other variants installed:** Frappe, Macchiato, Mocha static — available in `fish/themes/` but Mocha is active +- **No per-tool theming exceptions** — all tools must use Catppuccin Mocha + +## Editor: Neovim with lazy.nvim + +- **Decision:** Neovim (not VSCode or other) as primary editor +- **Plugin manager:** lazy.nvim (not packer, not vim-plug) — auto-bootstrapped from init.lua +- **LSP strategy:** mason.nvim for tooling installation + mason-lspconfig for auto-enable; capabilities injected globally via cmp_nvim_lsp +- **Format strategy:** conform.nvim with format-on-save (not LSP formatting directly); lsp_fallback=true for unconfigured filetypes +- **No treesitter-based formatting** — explicit per-filetype formatters in conform + +## OpenCode: Custom Multi-Agent Config + +- **Decision:** Fully custom multi-agent configuration (not default OpenCode setup) +- **10 specialized agents** each with tailored instructions, model, temperature, permissions +- **Memory pattern:** `.memory/` directory tracked in git; agents write to `.memory/*` directly +- **Permission model:** Full edit for lead/coder/librarian; all others restricted to `.memory/*` writes (instruction-level enforcement, not tool-level) +- **AGENTS.md exception:** In the opencode subdir, `AGENTS.md` is NOT a symlink (it's the global OpenCode config file, distinct from the per-project `AGENTS.md` pattern) +- See [OpenCode Architecture](research/opencode-architecture.md) for details + +## Waybar CPU Monitor: Ghostty (not Kitty) + +- **Observation:** `cpu` module in Waybar opens `ghostty -e htop` on click — Ghostty may be installed as secondary terminal +- **Impact:** Kitty is the primary terminal (SUPER+Return), but Ghostty is referenced in Waybar config + +## Git Credentials: gh CLI + +- **Decision:** Use `gh auth git-credential` as credential helper for GitHub + Gist +- **Rationale:** Centralizes auth through GitHub CLI; no plaintext tokens in git config + +## SSH Key Type: Ed25519 + +- **Decision:** Ed25519 for SSH key (not RSA) +- **Rationale:** Modern, fast, smaller key size + +## No Global `.gitignore` in Dotfiles + +- **Observation:** No global gitignore file visible; tracking is managed per-repo +- **Pattern:** Sensitive SSH private key `.ssh/id_ed25519` is tracked — implies this repo may use filesystem permissions for security diff --git a/.memory/knowledge.md b/.memory/knowledge.md new file mode 100644 index 0000000..1e05329 --- /dev/null +++ b/.memory/knowledge.md @@ -0,0 +1,188 @@ +# Dotfiles Knowledge + +## Project Purpose + +Personal dotfiles for `alex` on a Linux/Wayland desktop. Managed as a bare or normal git repo in `~/dotfiles/`. Covers the full desktop stack: shell, editor, compositor, terminal, status bar, notifications, and AI tooling. + +## Repository Layout + +``` +~/dotfiles/ +├── .bash_profile / .bashrc / .zshrc / .profile # Legacy/fallback shell configs +├── .gitconfig # Git global config (gh credential helper) +├── .ssh/ # SSH keys and known_hosts +└── .config/ + ├── dunst/ # Notification daemon + ├── fish/ # Primary shell + ├── hypr/ # Wayland compositor + screen lock + ├── kitty/ # Terminal emulator + ├── nvim/ # Editor (Neovim) + ├── opencode/ # AI coding assistant (complex subsystem) + ├── rofi/ # App launcher + ├── waybar/ # Status bar + └── zathura/ # PDF viewer +``` + +## Desktop Stack + +| Layer | Tool | Notes | +|---|---|---| +| Compositor | Hyprland | Wayland, tiling, dwindle layout | +| Terminal | Kitty | GPU-accelerated | +| Shell | Fish | Primary shell | +| Editor | Neovim | lazy.nvim plugin manager | +| Status bar | Waybar | Bottom layer, top position | +| App launcher | Rofi | `rofi -show drun` | +| Notifications | Dunst | | +| Screen lock | Hyprlock | `SUPER+C` | +| Screenshots | Hyprshot | Print=region, Shift+Print=output | +| File manager | Thunar | | +| Browser | Brave | `SUPER+B` / `SUPER+SHIFT+B` incognito | +| Email | Thunderbird | `SUPER+M` | +| VPN | ProtonVPN | Auto-started via hyprland exec-once | +| Mail bridge | Protonmail Bridge | Auto-started `--no-window` | +| PDF viewer | Zathura | | + +## Hyprland Configuration + +File: `.config/hypr/hyprland.conf` + +- **mainMod:** SUPER (`caps:super` — Caps Lock acts as Super) +- **Layout:** dwindle (no gaps, border_size=1, rounding=10) +- **Keyboard:** `us, br` layouts; `alts_toggle` (Alt+Shift switches layout) +- **Animations:** disabled +- **Autostart:** waybar, nm-applet, protonmail-bridge --no-window, protonvpn-app + +### Key Bindings +``` +SUPER+Return kitty +SUPER+Q kill window +SUPER+E thunar +SUPER+Space rofi +SUPER+F fullscreen +SUPER+B/Shift+B brave / brave --incognito +SUPER+M thunderbird +SUPER+V protonvpn-app +SUPER+C hyprlock +Print hyprshot -m region +Shift+Print hyprshot -m output +SUPER+h/j/k/l move focus (vim dirs) +SUPER+SHIFT+h/j/k/l move window +SUPER+1-9/0 switch workspace +SUPER+SHIFT+1-9/0 move to workspace +SUPER+S scratchpad toggle +SUPER+R resize submap (h/j/k/l = 30px steps) +``` + +## Theme: Catppuccin Mocha + +Applied uniformly across all tools: + +| Tool | Config file | +|---|---| +| Hyprland borders | `hyprland.conf` (lavender→mauve active, surface0 inactive) | +| Kitty | `kitty/kitty.conf` (full 16-color palette) | +| Neovim | `nvim/lua/plugins/colorscheme.lua` (catppuccin/nvim, flavour=mocha) | +| Fish | `fish/config.fish` (Catppuccin Mocha theme via fish_config) | +| Fish plugin | `fish/fish_plugins` (catppuccin/fish installed via fisher) | + +Key colors: bg=#1e1e2e, fg=#cdd6f4, lavender=#b4befe, mauve=#cba6f7, crust=#11111b, surface0=#313244 + +## Shell: Fish + +Files: `.config/fish/` + +- **Plugin manager:** fisher (jorgebucaran/fisher) +- **Plugins:** catppuccin/fish +- **Theme:** Catppuccin Mocha (set in config.fish) + +### Functions / Aliases +| Function | Expands to | Purpose | +|---|---|---| +| `c` | `opencode` | Launch OpenCode AI assistant | +| `cc` | `opencode --continue` | Continue last OpenCode session | +| `co` | `copilot` | GitHub Copilot CLI | +| `n` | `nvim` | Neovim | + +## Editor: Neovim + +Files: `.config/nvim/` + +- **Entry:** `init.lua` — sets `mapleader=`, bootstraps lazy.nvim +- **Plugins:** all in `lua/plugins/`, auto-loaded via `{ import = 'plugins' }` +- **Options:** `number=true`, `relativenumber=true`, `wrap=false` + +### Plugin List + +| Plugin | File | Purpose | +|---|---|---| +| catppuccin/nvim | colorscheme.lua | Mocha colorscheme, priority=1000 | +| nvim-cmp | cmp.lua | Completion engine | +| stevearc/conform.nvim | conform.lua | Format on save | +| folke/lazydev | lazydev.lua | Neovim Lua dev assistance | +| neovim/nvim-lspconfig | lspconfig.lua | LSP client config | +| L3MON4D3/LuaSnip | luasnip.lua | Snippet engine | +| williamboman/mason.nvim | mason.lua | LSP/tool installer UI | +| mason-lspconfig.nvim | mason-lspconfig.lua | Mason+LSP bridge, auto-install | +| jay-babu/mason-null-ls | mason-null-ls.lua | Mason+null-ls bridge | +| nvimtools/none-ls | none-ls.lua | LSP diagnostics from external tools | +| opencode-ai/nvim-opencode | opencode.lua | OpenCode integration | +| nvim-telescope/telescope | telescope.lua | Fuzzy finder | +| nvim-treesitter | treesitter.lua | Syntax parsing | + +### Keymaps +``` +e vim.cmd.Ex (file explorer) +ww save file +ff Telescope find_files +fg Telescope live_grep +fb Telescope buffers +fh Telescope help_tags +f Conform format (async) +``` + +### LSP / Formatting +- **mason-lspconfig:** `automatic_installation=true`, `automatic_enable=true`; injects `cmp_nvim_lsp` capabilities to all LSP servers globally +- **conform formatters by filetype:** + - lua → stylua + - js/ts/jsx/tsx/json/yaml/md → prettier + - python → ruff_format + - go → gofmt +- **format_on_save:** timeout_ms=500, lsp_fallback=true +- **Diagnostics:** virtual_text, signs, underline; float border=rounded, source=always + +## Status Bar: Waybar + +File: `.config/waybar/config` + `style.css` + `scripts/pomodoro-preset.sh` + +- Layer: bottom, position: top, spacing: 6 +- **Left:** backlight, wireplumber, custom/pomodoro +- **Center:** clock (`{:%H:%M - %a,%d}`, interval=1) +- **Right:** tray, bluetooth, temperature, cpu, memory, battery +- **Pomodoro:** external `waybar-module-pomodoro` binary; left=toggle, right=preset script, middle=reset +- **Custom/music:** playerctl metadata polling (interval=5) +- CPU click: `ghostty -e htop` (note: Ghostty not Kitty here) +- Bluetooth click: blueman-manager + +## OpenCode AI System + +Files: `.config/opencode/` + +The most complex subsystem. Full multi-agent AI coding assistant configuration. +See [OpenCode Architecture](research/opencode-architecture.md) for detailed breakdown. + +**Quick reference:** +- Config: `opencode.jsonc` (default_agent=lead, plugin=@tarquinen/opencode-dcp) +- Agents: `agents/*.md` (10 agents: lead, coder, reviewer, tester, explorer, researcher, librarian, critic, sme, designer) +- Memory: `agents/.memory/` — persistent knowledge for the AI system itself +- Instruction files: `.github/copilot-instructions.md` (canonical), `CLAUDE.md` + `.cursorrules` (symlinks); `AGENTS.md` is NOT a symlink (global OpenCode config) +- MCP servers: context7 (remote docs), gh_grep (remote code search), playwright (local Chromium) +- Skills: `skills/doc-coverage/`, `skills/git-workflow/`, `skills/work-decomposition/` + +## Git Configuration + +File: `.gitconfig` + +- `user.name=alex`, `user.email=misc@wiesner.com.br` +- `init.defaultBranch=main` +- Credential helper: `!/usr/bin/gh auth git-credential` (GitHub + Gist) diff --git a/.memory/plans/.gitkeep b/.memory/plans/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.memory/research/.gitkeep b/.memory/research/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.memory/research/opencode-architecture.md b/.memory/research/opencode-architecture.md new file mode 100644 index 0000000..ea07b92 --- /dev/null +++ b/.memory/research/opencode-architecture.md @@ -0,0 +1,106 @@ +# OpenCode Architecture Research + +## Overview + +The OpenCode multi-agent configuration lives at `.config/opencode/` and is the most complex subsystem in this dotfiles repo. + +## Directory Structure + +``` +.config/opencode/ +├── opencode.jsonc # Main config +├── AGENTS.md # Global OpenCode config (NOT a symlink here) +├── CLAUDE.md -> .github/copilot-instructions.md (symlink) +├── .cursorrules -> .github/copilot-instructions.md (symlink) +├── .github/ +│ └── copilot-instructions.md # Canonical cross-tool instructions +├── agents/ +│ ├── lead.md # Primary orchestrator (mode=primary, temp=0.3) +│ ├── coder.md # Implementation agent +│ ├── reviewer.md # Code review (read-only) +│ ├── tester.md # Testing/validation +│ ├── explorer.md # Codebase mapper +│ ├── researcher.md # Technical investigator +│ ├── librarian.md # Documentation specialist +│ ├── critic.md # Plan gate +│ ├── sme.md # Domain expert consultant +│ └── designer.md # UI/UX specialist +├── .memory/ +│ ├── knowledge.md # OpenCode-specific architecture knowledge +│ ├── decisions.md # Agent permission decisions, symlink strategy +│ ├── plans/ # Active feature plans +│ └── research/ # Research findings +└── skills/ + ├── doc-coverage/SKILL.md # Documentation coverage checklist + ├── git-workflow/SKILL.md # Git commit/worktree/PR procedures + └── work-decomposition/SKILL.md # Multi-feature decomposition +``` + +## opencode.jsonc Key Settings + +```jsonc +{ + "default_agent": "lead", + "autoupdate": true, + "plugin": "@tarquinen/opencode-dcp", + "agents": { + "general": { "disabled": true }, + "explore": { "disabled": true }, + "plan": { "permissions": { "write": "allow" } } + }, + "permissions": { + "websearch": "allow", + "question": "allow", + "external_directory": "deny" + }, + "mcp": { + "context7": { "url": "https://mcp.context7.com/mcp", "type": "remote" }, + "gh_grep": { "url": "https://mcp.grep.app", "type": "remote" }, + "playwright": { "command": "npx @playwright/mcp@latest --headless --browser chromium", "type": "local" } + } +} +``` + +## Agent Model/Permission Matrix + +| Agent | Model | Full Edit | Notes | +|---|---|---|---| +| lead | claude-opus-4 | ✅ | Orchestrator, all task types | +| coder | gpt-5.3-codex | ✅ | Implementation | +| librarian | claude-opus-4.6 | ✅ | Documentation | +| reviewer | claude-opus-4.6 | `.memory/*` only | Read-only code review | +| tester | claude-sonnet-4.6 | `.memory/*` only | Validation | +| explorer | claude-sonnet-4.6 | `.memory/*` only | Codebase mapping | +| researcher | claude-opus-4.6 | `.memory/*` only | Technical research | +| critic | claude-opus-4.6 | `.memory/*` only | Plan gate | +| sme | claude-opus-4.6 | `.memory/*` only | Domain expert | +| designer | claude-sonnet-4.6 | `.memory/*` only | UI/UX | + +## Lead Agent Workflow + +Phases: CLARIFY → DISCOVER → CONSULT → PLAN → CRITIC-GATE → EXECUTE → PHASE-WRAP + +- **Tiered quality pipeline:** Tier 1 (full, new features), Tier 2 (standard), Tier 3 (fast, trivial) +- **Worktrees:** `.worktrees/` per feature branch +- **Retry circuit breaker:** 3 coder rejections → redesign; 5 failures → escalate +- **Commit format:** Conventional Commits (`feat:`, `fix:`, `chore:`, etc.) +- **Parallelization:** mandatory for independent work + +## Memory Pattern + +- `.memory/` tracked in git for cross-session persistence +- Agents with `.memory/*` write permission record directly (instruction-level enforcement) +- Structure: `knowledge.md` (architecture), `decisions.md` (design choices), `plans/.md`, `research/.md` + +## Cross-Tool Instruction Files + +- `.github/copilot-instructions.md` = single source of truth +- `CLAUDE.md` and `.cursorrules` = symlinks +- `AGENTS.md` = NOT a symlink in this repo (serves as global OpenCode config) +- **Note:** In OTHER projects, `AGENTS.md` should be a symlink. The OpenCode config dir is a special case. + +## Skills + +- **doc-coverage:** Validates canonical instruction file + symlinks; checks README + docs/* coverage +- **git-workflow:** Step-by-step git commit, worktree, and PR creation procedures +- **work-decomposition:** Splits 3+ feature requests into independent workstreams with separate worktrees