Document findings from database investigation:
- Session table schema with all fields explained
- Session ID format and generation (unique, no duplicates)
- Parent-child relationships for forked sessions
- Session detection logic used by kugetsu
- Permission structure and common issues
- SQL queries for debugging session problems
- Known issues and solutions (from #81, #36)
This document helps future debugging of session-related issues
without having to investigate opencode internals directly.
Phase 3c implementation - Notification System:
### New kugetsu commands:
- `kugetsu notify list` - Show unread notifications from PM Agent
- `kugetsu notify clear` - Mark notifications as read
### Notification system:
- PM Agent writes task events to ~/.kugetsu/notifications.json
- Events: task_complete, task_blocked, task_assigned
- Supports issue_ref and gitea_url for linking
- Hermes/Chat Agent reads notifications on user messages
### kugetsu-pm v2.0:
- Updated documentation with notification behavior
- PM Agent monitors Gitea for task completion
- Two review modes: PM reviews immediately OR asks dev if ready
- Notification triggers documented
### File renamed:
- phase3a-setup.md → kugetsu-chat-setup.md (more descriptive)
### Hermes gateway analysis:
- Gateway is a client (connects to Telegram), not a server
- Cannot push messages directly to Telegram from external process
- Notifications stored locally for Hermes to pick up on next user message
This commit implements Phase 3b/3c architectural improvements:
### New kugetsu CLI commands:
- `kugetsu status` - Check initialization status (replaces kugetsu-helper check-status)
- `kugetsu delegate <msg>` - Send message to PM agent (new command)
- `kugetsu doctor [--fix]` - Diagnose and fix kugetsu issues
### PM Context Injection:
- kugetsu init now reads ~/.kugetsu/pm-agent.md (if exists) and injects
it into the PM agent session at creation time
- PM context is loaded ONCE at init, not on every delegation
- This improves efficiency - kugetsu-pm content read once, not 10 times
### kugetsu-chat updated:
- Now uses `kugetsu delegate` instead of kugetsu-helper
- Now uses `kugetsu status` instead of kugetsu-helper check-status
- Simplified - no longer depends on kugetsu-helpers
### kugetsu continue:
- Removed strict issue-ref format validation
- Now accepts any session name that is tracked in index.json["issues"]
- Issue-ref format is a guideline, not a hard requirement
### Documentation updated:
- phase3a-setup.md - Updated to reflect new kugetsu commands
- kugetsu-install.sh - Simplified Phase 3a setup instructions
### Breaking changes:
- kugetsu-helpers is no longer required for Phase 3a Chat Agent
- kugetsu-chat skill v3.0 now requires kugetsu CLI with new commands
- Identify delegate_task() (max 3) vs terminal(opencode run) (no cap)
- Document Gitea as async communication hub
- PM ↔ Coding Agent communication protocols
- Practical examples for each pattern
- Issue state machine and known limitations
- sshd-setup.sh: Auto-detect OS (Debian/Ubuntu/Fedora/RHEL/CentOS)
- Use appropriate package manager (apt-get vs dnf)
- Add verification steps after each major phase
- Exit with error if sshd installation fails
- Exit with error if sshd doesn't start successfully
- Add troubleshooting section in output
- kugetsu-install.sh: Add verification that kugetsu binary exists
- kugetsu-setup.md: Document multi-distro installation commands
- Installation via curl script (with --skip-setup for CI)
- API key configuration for 9+ LLM providers
- OpenCode delegation via terminal() wrapper pattern
- Git worktree isolation per-issue workflow
- Reference to existing opencode-worktree skill
Related to issue #1
Document:
- How to detect contamination via git log and branch --contains
- Prevention with explicit base: git checkout -b new-branch main
- Fix using git rebase --onto
- Force push with --force-with-lease for safety
Addresses Issue #1 comment 281
