* Use conventional commits (`feat:`, `fix:`, `docs:`, `chore:`, etc.) scoped to the keyboard where relevant (e.g. `feat(q5_max):`).
* Do **not** include `Co-Authored-By: Claude` trailers in commit messages.
### Chained / Stacked PRs
When merging a chain of PRs (e.g. `A → main`, `B → A`, `C → B`), always **delete the branch after each merge**. Gitea (and GitHub) will automatically retarget any open PRs pointing at the deleted branch to the branch it was merged into. This keeps the chain collapsing cleanly into `main` without manual retargeting or cleanup PRs.
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Replace the plain Caps Lock key with a smart `CAPS_MOD` key: tap=ESC, hold=Ctrl, Shift+tap=CapsLock, Alt+tap=CapsWord, GUI+tap=Autocorrect toggle, with RGB indicators on the Caps Lock key.
**Architecture:** Custom keycode `CAPS_MOD` with a timer-based tap/hold split. `process_record_user` starts the timer on press and dispatches actions on release. `matrix_scan_user` promotes a held key to Ctrl once `TAPPING_TERM` elapses. RGB indicators for CapsWord (green), Autocorrect (purple), and host CapsLock (white) are added to the existing `rgb_matrix_indicators_advanced_user` function.
**Tech Stack:** QMK firmware (C), RGB Matrix, Caps Word, Autocorrect — all built in to QMK.
source .venv/bin/activate && qmk compile -kb keychron/q5_max/ansi_encoder -km via
```
---
## File Map
| File | Change |
|---|---|
| `keyboards/keychron/q5_max/ansi_encoder/keymaps/via/rules.mk` | Add `CAPS_WORD_ENABLE` and `AUTOCORRECT_ENABLE` |
| `keyboards/keychron/q5_max/ansi_encoder/keymaps/via/config.h` | No change needed (`AUTOCORRECT_MIN_LENGTH` already defined in `autocorrect_data.h`) |
| `keyboards/keychron/q5_max/ansi_encoder/keymaps/via/autocorrect_data.h` | Commit to git (was untracked; pre-generated dictionary with `AUTOCORRECT_MIN_LENGTH 4` already inside) |
| `keyboards/keychron/q5_max/ansi_encoder/keymaps/via/keymap.c` | Add `CAPS_MOD` to enum; add state vars; replace all `KC_CAPS`; add press/release + scan logic; add LED 55 indicators |
---
## Task 1: Enable Caps Word and Autocorrect features
- Note: `config.h` needs no change — `AUTOCORRECT_MIN_LENGTH 4` is already defined inside `autocorrect_data.h`
- [ ]**Step 1: Add feature flags to rules.mk**
Replace the entire file content with:
```makefile
VIA_ENABLE= yes
TAP_DANCE_ENABLE= yes
UNICODE_ENABLE= yes
COMBO_ENABLE= yes
CAPS_WORD_ENABLE= yes
AUTOCORRECT_ENABLE= yes
SRC+= chord_unicode.c
```
- [ ]**Step 2: Verify autocorrect_data.h is present and has AUTOCORRECT_MIN_LENGTH**
Check that `keyboards/keychron/q5_max/ansi_encoder/keymaps/via/autocorrect_data.h` exists and contains `#define AUTOCORRECT_MIN_LENGTH`. Do NOT add it to `config.h` — it is already defined in the pre-generated file.
- [ ]**Step 3: Compile to verify no breakage**
```bash
source .venv/bin/activate && qmk compile -kb keychron/q5_max/ansi_encoder -km via
```
Expected: build succeeds, `.bin` file produced. No errors.
- [ ]**Step 3: Replace KC_CAPS with CAPS_MOD in all five layers**
In the keymap arrays, find every occurrence of `KC_CAPS` and replace with `CAPS_MOD`. There are five instances — one at the start of row 3 in each of: BASE, FN1, FN2, FN3, FN4. KEEB_CTL already uses `_______` for that position and stays unchanged.
Each row looks like:
```c
KC_CAPS,KC_A,KC_S,...
```
Change to:
```c
CAPS_MOD,KC_A,KC_S,...
```
Do this for all five layers.
- [ ]**Step 4: Compile to verify**
```bash
source .venv/bin/activate && qmk compile -kb keychron/q5_max/ansi_encoder -km via
```
Expected: build succeeds. `CAPS_MOD` is defined but not yet handled — QMK will pass it through to `process_record_user` which returns `true` by default, so no errors.
- [ ]**Step 1: Add CAPS_MOD case to the switch in process_record_user**
Find the `switch (keycode)` block in `process_record_user`. It currently starts with `case LCK_FN1:`. Add the `CAPS_MOD` case **before** the `LCK_FN1` case:
```c
caseCAPS_MOD:
if(record->event.pressed){
caps_mod_held=true;
caps_mod_timer=timer_read();
}else{
if(caps_mod_ctrl_registered){
unregister_code(KC_LCTL);
caps_mod_ctrl_registered=false;
}else{
uint8_tmods=get_mods();
if(mods&MOD_MASK_GUI){
autocorrect_toggle();
}elseif(mods&MOD_MASK_ALT){
caps_word_toggle();
}elseif(mods&MOD_MASK_SHIFT){
tap_code(KC_CAPS);
}else{
tap_code(KC_ESC);
}
}
caps_mod_held=false;
}
returnfalse;
```
- [ ]**Step 2: Add Ctrl promotion to matrix_scan_user**
source .venv/bin/activate && qmk compile -kb keychron/q5_max/ansi_encoder -km via
```
Expected: build succeeds, no errors or warnings about undefined functions. (`autocorrect_toggle`, `caps_word_toggle`, `get_mods`, `MOD_MASK_*` are all QMK builtins.)
RGB_MATRIX_INDICATOR_SET_COLOR(55,0,200,0);// green: Caps Word active
}elseif(autocorrect_is_enabled()){
RGB_MATRIX_INDICATOR_SET_COLOR(55,150,0,255);// purple: Autocorrect active
}elseif(host_keyboard_led_state().caps_lock){
RGB_MATRIX_INDICATOR_SET_COLOR(55,255,255,255);// white: normal Caps Lock on
}else{
RGB_MATRIX_INDICATOR_SET_COLOR(55,0,0,0);// off
}
returnfalse;
}
```
- [ ]**Step 2: Compile to verify**
```bash
source .venv/bin/activate && qmk compile -kb keychron/q5_max/ansi_encoder -km via
```
Expected: build succeeds. (`is_caps_word_on`, `autocorrect_is_enabled`, `host_keyboard_led_state` are all QMK builtins available when their features are enabled.)
Added inside `rgb_matrix_indicators_advanced_user`, checked in priority order:
| State | Color |
|---|---|
| Caps Word on | Green `(0, 200, 0)` |
| Autocorrect on | Purple `(150, 0, 255)` |
| Normal Caps Lock on | White `(255, 255, 255)` |
| All off | Dark `(0, 0, 0)` |
Caps Word takes visual priority over host Caps Lock because both can technically be
active simultaneously.
---
## Feature Enablement
### `rules.mk` additions
```makefile
CAPS_WORD_ENABLE= yes
AUTOCORRECT_ENABLE= yes
```
### `config.h` addition
```c
#define AUTOCORRECT_MIN_LENGTH 4
```
`autocorrect_data.h` is already present in the keymap folder. QMK picks it up
automatically when `AUTOCORRECT_ENABLE = yes` — no manual `#include` needed.
---
## Files Changed
| File | Change |
|---|---|
| `keymap.c` | Add `CAPS_MOD` to enum; add state vars; add press/release logic in `process_record_user`; add scan logic in `matrix_scan_user`; add LED 55 indicators in `rgb_matrix_indicators_advanced_user`; replace all `KC_CAPS` with `CAPS_MOD` |
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.