From 5e968b6c4a9ee60edc1983ed2bafbbf05637887e Mon Sep 17 00:00:00 2001
From: shokollm <270575765+shokollm@users.noreply.github.com>
Date: Wed, 1 Apr 2026 22:12:20 +0000
Subject: [PATCH] feat(kugetsu): add config file initialization and
 documentation

- Initialize default ~/.kugetsu/config during kugetsu init
- Document config override options in SKILL.md
- Addresses han's review feedback
---
 skills/kugetsu/SKILL.md        | 21 +++++++++++++++++++++
 skills/kugetsu/scripts/kugetsu | 12 ++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/skills/kugetsu/SKILL.md b/skills/kugetsu/SKILL.md
index 7d5a1ca..ddefcc3 100644
--- a/skills/kugetsu/SKILL.md
+++ b/skills/kugetsu/SKILL.md
@@ -27,6 +27,27 @@ cp skills/kugetsu/scripts/kugetsu ~/.local/bin/kugetsu
 chmod +x ~/.local/bin/kugetsu
 ```
 
+## Configuration
+
+User overrides can be set in `~/.kugetsu/config`. This file is sourced on each kugetsu command call, so changes take effect immediately without re-initialization.
+
+A default config file is created during `kugetsu init` with commented examples:
+
+```bash
+# User configuration overrides
+# Values set here take precedence over defaults
+# Changes take effect immediately (no re-init needed)
+
+# Max concurrent dev agents (default: 3)
+# MAX_CONCURRENT_AGENTS=5
+```
+
+### Available Config Options
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MAX_CONCURRENT_AGENTS` | 3 | Maximum number of concurrent dev agents |
+
 ## Architecture
 
 ### Session Pattern
diff --git a/skills/kugetsu/scripts/kugetsu b/skills/kugetsu/scripts/kugetsu
index 0b3aa24..66653f9 100755
--- a/skills/kugetsu/scripts/kugetsu
+++ b/skills/kugetsu/scripts/kugetsu
@@ -686,6 +686,18 @@ cmd_init() {
 
     ensure_dirs
 
+    if [ ! -f "$KUGETSU_DIR/config" ]; then
+        cat > "$KUGETSU_DIR/config" << 'EOF'
+# User configuration overrides
+# Values set here take precedence over defaults
+# Changes take effect immediately (no re-init needed)
+
+# Max concurrent dev agents (default: 3)
+# MAX_CONCURRENT_AGENTS=5
+EOF
+        echo "Created config file: $KUGETSU_DIR/config"
+    fi
+
     local existing_base=$(get_base_session_id)
     local existing_pm=$(get_pm_agent_session_id)