alex/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: bootstrap .memory/ project knowledge files

Browse Source 
Add initial .memory/ knowledge base for the dotfiles repo:
- knowledge.md: full desktop stack, tool configs, keybindings, conventions
- decisions.md: architectural choices (Hyprland, Fish, Catppuccin Mocha, Neovim, OpenCode)
- research/opencode-architecture.md: detailed OpenCode multi-agent system breakdown
This commit is contained in:
alex
2026-03-09 12:27:12 +00:00
parent 2b2dd11575
commit 20b7ef0ea6
5 changed files with 353 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
.memory/decisions.md Normal file
View File

@@ -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

188
.memory/knowledge.md Normal file
View File

@@ -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=<Space>`, 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
```
<leader>e vim.cmd.Ex (file explorer)
<leader>ww save file
<leader>ff Telescope find_files
<leader>fg Telescope live_grep
<leader>fb Telescope buffers
<leader>fh Telescope help_tags
<leader>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)

0
.memory/plans/.gitkeep Normal file
View File

0
.memory/research/.gitkeep Normal file
View File

106
.memory/research/opencode-architecture.md Normal file
View File

@@ -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/<feature-name>` 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/<feature>.md`, `research/<topic>.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