feat(kugetsu): auto-create pm-agent session during init
- kugetsu init now creates both base and pm-agent sessions - kugetsu start checks for pm-agent existence, errors if missing - Add kugetsu destroy --pm-agent command - Update list to show pm-agent session - Update prune to preserve pm-agent.json - Update SKILL.md documentation to v2.1 Part of issue #19 Phase 3 implementation
This commit is contained in:
shokollm
@@ -5,7 +5,7 @@ license: MIT
|
||||
compatibility: Requires opencode CLI, bash, python3, and filesystem access.
|
||||
metadata:
|
||||
author: shoko
|
||||
version: "2.0"
|
||||
version: "2.1"
|
||||
---
|
||||
|
||||
# kugetsu - OpenCode Session Manager (Issue-Driven)
|
||||
@@ -30,7 +30,8 @@ chmod +x ~/.local/bin/kugetsu
|
||||
## Architecture
|
||||
|
||||
### Session Pattern
|
||||
- **Base Session**: Created once via TUI, used for forking
|
||||
- **Base Session**: Created once via TUI, used for forking dev agents
|
||||
- **PM Agent Session**: Created during init, persistent coordinator for task management
|
||||
- **Forked Sessions**: One per issue, branched from base via `opencode run --fork --session <base>`
|
||||
|
||||
### Directory Structure
|
||||
@@ -38,14 +39,16 @@ chmod +x ~/.local/bin/kugetsu
|
||||
~/.kugetsu/
|
||||
├── sessions/
|
||||
│ ├── base.json # Base session metadata
|
||||
│ ├── pm-agent.json # PM agent session metadata
|
||||
│ └── github.com-shoko-kugetsu-14.json # Forked session per issue
|
||||
└── index.json # Maps issue refs to session files
|
||||
└── index.json # Maps session IDs and issue refs to session files
|
||||
```
|
||||
|
||||
### Index File
|
||||
```json
|
||||
{
|
||||
"base": "ses_abc123",
|
||||
"pm_agent": "ses_pm_xyz789",
|
||||
"issues": {
|
||||
"github.com/shoko/kugetsu#14": "github.com-shoko-kugetsu-14.json"
|
||||
}
|
||||
@@ -55,8 +58,7 @@ chmod +x ~/.local/bin/kugetsu
|
||||
### Session File
|
||||
```json
|
||||
{
|
||||
"type": "base|forked",
|
||||
"issue_ref": "github.com/shoko/kugetsu#14",
|
||||
"type": "base|forked|pm_agent",
|
||||
"opencode_session_id": "ses_xyz789",
|
||||
"created_at": "2026-03-29T18:16:10+02:00",
|
||||
"state": "idle"
|
||||
@@ -76,11 +78,90 @@ Examples:
|
||||
|
||||
### kugetsu init [--force]
|
||||
|
||||
Initialize base session via TUI:
|
||||
Initialize base + PM agent sessions via TUI:
|
||||
```bash
|
||||
kugetsu init
|
||||
```
|
||||
|
||||
- Requires a terminal (TTY) to spawn the opencode TUI
|
||||
- Creates base session and PM agent session
|
||||
- Stores both session IDs in `index.json`
|
||||
- Subsequent runs error unless `--force` is used
|
||||
|
||||
### kugetsu start `<issue-ref>` `<message>` [--debug]
|
||||
|
||||
Start task for an issue by forking from base session:
|
||||
```bash
|
||||
kugetsu start github.com/shoko/kugetsu#14 "fix authentication bug"
|
||||
```
|
||||
|
||||
- Forks new session from base
|
||||
- Requires PM agent to exist (created by init)
|
||||
- Stores mapping in `index.json`
|
||||
- Uses `opencode run --fork --session <base-session-id> "<message>"`
|
||||
|
||||
### kugetsu continue `<issue-ref>` `<message>` [--debug]
|
||||
|
||||
Continue work on an existing issue session:
|
||||
```bash
|
||||
kugetsu continue github.com/shoko/kugetsu#14 "add unit tests"
|
||||
```
|
||||
|
||||
- Looks up session file from index
|
||||
- Uses `opencode run --continue --session <opencode-session-id> "<message>"`
|
||||
|
||||
### kugetsu list
|
||||
|
||||
List all tracked sessions:
|
||||
```bash
|
||||
kugetsu list
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
ISSUE_REF TYPE SESSION_ID CREATED
|
||||
─────────────────────────────────────────────────────────────────────────────────────────────────
|
||||
(base) base ses_abc123 N/A
|
||||
(pm-agent) pm_agent ses_pm_xyz789 2026-03-29T18:16:10+02:00
|
||||
github.com/shoko/kugetsu#14 forked ses_xyz789 2026-03-29T18:16:10+02:00
|
||||
```
|
||||
|
||||
### kugetsu prune [--force]
|
||||
|
||||
Remove orphaned sessions (files not in index):
|
||||
```bash
|
||||
kugetsu prune # Shows what would be deleted
|
||||
kugetsu prune --force # Deletes orphaned sessions
|
||||
```
|
||||
|
||||
- Orphaned = session files in `sessions/` but not in `index.json`
|
||||
- Always keeps `base.json` and `pm-agent.json`
|
||||
- Useful after opencode session cleanup
|
||||
|
||||
### kugetsu destroy `<issue-ref>` [-y]
|
||||
|
||||
Delete session for specific issue:
|
||||
```bash
|
||||
kugetsu destroy github.com/shoko/kugetsu#14 # Prompts for confirmation
|
||||
kugetsu destroy github.com/shoko/kugetsu#14 -y # Skips confirmation
|
||||
```
|
||||
|
||||
### kugetsu destroy --pm-agent [-y]
|
||||
|
||||
Delete PM agent session (requires explicit `--pm-agent`):
|
||||
```bash
|
||||
kugetsu destroy --pm-agent -y
|
||||
```
|
||||
|
||||
### kugetsu destroy --base [-y]
|
||||
|
||||
Delete base session (requires explicit `--base`):
|
||||
```bash
|
||||
kugetsu destroy --base -y
|
||||
```
|
||||
|
||||
**Note**: Destroying base also destroys PM agent since PM depends on base.
|
||||
|
||||
- Requires a terminal (TTY) to spawn the opencode TUI
|
||||
- Creates base session once; subsequent runs error unless `--force` is used
|
||||
- Stores base session ID in `index.json`
|
||||
@@ -153,6 +234,7 @@ kugetsu destroy --base -y
|
||||
```bash
|
||||
# First-time setup (requires TTY)
|
||||
kugetsu init
|
||||
# Creates: base session + pm-agent session
|
||||
|
||||
# Start work on issue
|
||||
kugetsu start github.com/shoko/kugetsu#14 "implement feature X"
|
||||
@@ -182,6 +264,7 @@ This design solves the headless CLI limitation discovered in Issue #14:
|
||||
|
||||
The pattern:
|
||||
- Base session created once via TUI (interactive)
|
||||
- PM agent session created during init (persistent coordinator)
|
||||
- All subsequent work uses `--fork --session <base>` or `--continue --session <forked>`
|
||||
|
||||
## Recovery
|
||||
|
||||
Reference in New Issue
Block a user