diff --git a/skills/kugetsu/SKILL.md b/skills/kugetsu/SKILL.md index 5f3fa74..fb2f26e 100644 --- a/skills/kugetsu/SKILL.md +++ b/skills/kugetsu/SKILL.md @@ -49,6 +49,9 @@ A default config file is created during `kugetsu init` with commented examples: | `MAX_CONCURRENT_AGENTS` | 3 | Maximum number of concurrent dev agents | | `KUGETSU_TEMP_DIR` | `~/.local/share/opencode/tool-output` | Temp directory for subagent tool output (useful in headless environments where /tmp is restricted) | | `KUGETSU_VERBOSITY` | `default` | PM agent verbosity level: `verbose`, `default`, or `quiet` | +| `QUEUE_DAEMON_INTERVAL_MINUTES` | 5 | How often daemon polls queue (in minutes) | +| `QUEUE_DAEMON_BATCH_SIZE` | 2 | How many tasks daemon picks per poll | +| `QUEUE_CLEANUP_AGE_DAYS` | 7 | Auto-cleanup completed/error items older than N days | ### Environment Variables for Agents @@ -111,6 +114,10 @@ Each issue session gets its own git worktree to prevent conflicts: ├── worktrees/ │ ├── github.com-shoko-kugetsu-14/ # Isolated workdir for issue #14 │ └── github.com-shoko-kugetsu-15/ # Isolated workdir for issue #15 +├── queue/ +│ ├── items/ # Queue item JSON files +│ ├── daemon.pid # Daemon process ID +│ └── daemon.log # Daemon log output └── index.json # Maps session IDs and issue refs to session files ``` @@ -258,16 +265,17 @@ kugetsu destroy --base -y ### kugetsu delegate `` -Send a message to the PM agent for task coordination (fire-and-forget): +Send a message to the PM agent for task coordination via queue: ```bash kugetsu delegate "work on issue #14" kugetsu delegate "review PR #92" ``` -- Non-blocking: returns immediately, runs in background -- PM agent processes the message asynchronously -- Uses `KUGETSU_VERBOSITY` env var to control PM agent output verbosity -- Log output stored in `~/.kugetsu/logs/delegate-.log` +- **Always enqueues** (fire-and-forget): returns immediately +- Queue daemon polls queue and invokes PM when slots available +- Tasks are processed FIFO (first-in-first-out) +- Use `kugetsu queue list` to see pending tasks +- Use `kugetsu queue-daemon logs` to debug queue processing ### kugetsu logs [n] @@ -328,35 +336,79 @@ kugetsu server default github # Set default server kugetsu server get github # Get server URL ``` -### kugetsu queue +### kugetsu queue Manage task queue for autonomous PM operation: ```bash -kugetsu queue list # Show queued tasks -kugetsu queue enqueue "task" # Add task to queue -kugetsu queue dequeue # Remove next task from queue -kugetsu queue clear # Clear all queued tasks +kugetsu queue list # Show queued tasks with status +kugetsu queue stats # Show queue statistics (total, pending, notified, completed, error) +kugetsu queue clear # Clean up old completed/error items +kugetsu queue enqueue # Manually enqueue a task ``` -- Queue stored in `~/.kugetsu/queue.json` +**Queue Item States:** +- `pending` - Waiting in queue, daemon can pick up +- `notified` - PM agent has picked up the task +- `completed` - Dev agent finished, PR created +- `error` - Timeout or failure + +### kugetsu queue-daemon + +Manage the queue daemon background process: +```bash +kugetsu queue-daemon start # Start daemon in background +kugetsu queue-daemon stop # Stop daemon +kugetsu queue-daemon restart # Restart daemon +kugetsu queue-daemon status # Check if daemon is running +kugetsu queue-daemon logs # Show recent daemon logs +``` + +**Daemon Behavior:** +1. Runs at configurable interval (default: 5 minutes) +2. Checks if active agents < MAX_CONCURRENT_AGENTS +3. Picks 1-N pending items (configurable batch size) +4. Forks PM session for each picked item +5. PM decides whether to use `start` or `continue` + +**Queue Directory:** +``` +~/.kugetsu/queue/ +├── items/ # Queue item JSON files +│ ├── q_1234567890.json # One file per queued task +│ └── q_1234567891.json +├── daemon.pid # Daemon process ID +├── daemon.lock # Daemon lock file +└── daemon.log # Daemon log output +``` ## Workflow Example +### First-time Setup ```bash -# First-time setup (requires TTY) +# Initialize kugetsu (requires TTY) kugetsu init -# Creates: base session + pm-agent session -# Start work on issue -kugetsu start github.com/shoko/kugetsu#14 "implement feature X" -# Creates: worktree at ~/.kugetsu/worktrees/github.com-shoko-kugetsu-14/ +# Start the queue daemon (for autonomous operation) +kugetsu queue-daemon start +``` -# Continue later +### Normal Workflow +```bash +# Enqueue tasks via delegate - agents will process them automatically +kugetsu delegate "work on issue #14" +kugetsu delegate "review PR #92" + +# Check queue status +kugetsu queue list # See pending tasks +kugetsu queue stats # See statistics + +# Debug queue daemon +kugetsu queue-daemon status # Is daemon running? +kugetsu queue-daemon logs # See daemon logs + +# Continue work on existing issue kugetsu continue github.com/shoko/kugetsu#14 "add tests" -# Continue again -kugetsu continue github.com/shoko/kugetsu#14 "fix failing test" - # List all sessions kugetsu list @@ -367,6 +419,21 @@ kugetsu prune --force kugetsu destroy github.com/shoko/kugetsu#14 ``` +### Queue Daemon Management +```bash +# Check if daemon is running +kugetsu queue-daemon status + +# View daemon logs for debugging +kugetsu queue-daemon logs + +# Restart daemon if needed +kugetsu queue-daemon restart + +# Stop daemon +kugetsu queue-daemon stop +``` + ## Headless Operation This design solves the headless CLI limitation discovered in Issue #14: