Skip to content

armgit / agtx

Public Imported from GitHub
0

πŸ„πŸΌβ€β™‚οΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.

feat: extend orchestrate skill (#47)

Fynn FlΓΌgge6a02cdb09efa
diff --git a/README.md b/README.md
index ccefa72..75c2889 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
> **An AI agent that manages other coding agents in a terminal kanban board** - Add tasks. Press one key. An orchestrator agent picks it up, plans, and delegates to multiple coding agents running in parallel. Come back to changes ready to merge.
>
> **Let different AI coding agents collaborate** autonomously on the same task with automatic session switching and context awareness -
-> e.g.   **Gemini β†’ research**   |   **Claude β†’ implement**   |   **Codex β†’ review**
+> e.g. **Gemini** β†’ research | **Claude** β†’ implement | **Codex** β†’ review
</div>
@@ -45,11 +45,16 @@ With the orchestrator, you don't even manage the board yourself. **An AI agent p
- **Orchestrator agent**: A dedicated AI agent that autonomously manages your kanban board via [MCP](https://modelcontextprotocol.io) β€” delegates to coding agents, advances phases, checks for merge conflicts ([experimental](#orchestrator-agent-experimental))
- **Multi-agent task lifecycle**: Configure different agents per workflow phase β€” e.g. Gemini for research, Claude for implementation, Codex for review β€” with automatic agent switching
-- **Parallel execution**: Every task gets its own git worktree and tmux window β€” run as many agents as you want, simultaneously
+- **Parallel execution**: Every task gets its own git worktree and tmux window β€” run as many agents as needed, simultaneously
- **Spec-driven plugins**: Plug in [GSD](https://github.com/fynnfluegge/get-shit-done-cc), [Spec-kit](https://github.com/github/spec-kit), [OpenSpec](https://github.com/Fission-AI/OpenSpec), [BMAD](https://github.com/bmad-code-org/BMAD-METHOD), [Superpowers](https://github.com/obra/superpowers) β€” or define your own with a single TOML file
-- **Multi-project dashboard**: Manage agent sessions across all your projects from one place
+- **Multi-project dashboard**: Manage agent sessions across all projects via a single TUI
- **Works with**: [Claude Code](https://github.com/anthropics/claude-code) | [Codex](https://github.com/openai/codex) | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | [OpenCode](https://github.com/sst/opencode) | [Cursor Agent](https://cursor.com/docs/cli/overview) | [Copilot](https://github.com/github/copilot-cli)
+> [!NOTE]
+> Just need a plain coding agent session manager with **full human-in-the-loop control** and **no automatic spec-driven skill execution and orchestration** on advancing tasks?
+>
+> Choose the **`void` plugin** and enjoy the kanban coding agent board - with full human control.
+
## Quick Start
```bash
diff --git a/plugins/agtx/skills/orchestrate.md b/plugins/agtx/skills/orchestrate.md
index e3fa03e..4eeeaf1 100644
--- a/plugins/agtx/skills/orchestrate.md
+++ b/plugins/agtx/skills/orchestrate.md
@@ -92,26 +92,108 @@ Backlog β†’ Research β†’ Planning β†’ Running β†’ Review
When you receive a notification like:
```
-Task "fix-auth" (abc12345) has been idle for 5m in phase: running
+Task "fix-auth" (abc12345) has been idle for 1m in phase: running
```
1. Call `read_pane_content(task_id)` to see what the agent is showing.
-2. Analyze what you see:
- - **Agent asking a domain question** (ends with `?`, "Should I...", "Do you want to...",
- "Which approach...", anything requiring the user's judgment about the project):
- Call `move_task` with `action: "escalate_to_user"` and set `reason` to a brief
- summary of what the agent is asking. **Do NOT answer domain questions on the user's behalf.**
- - **CLI confirmation prompt** (`[y/N]`, `[Y/n]`, numbered menu like `1)`, `2)`, `3)`,
- "Press Enter to continue", "Continue? (yes/no)"):
- Call `send_to_task` with the appropriate response (e.g. `"y"`, `"1"`, `""`).
- Then call `read_pane_content` again after a few seconds to verify it was dismissed.
- - **Agent appears stuck on an error, in a loop, or confused**:
- Compose a short nudge prompt summarizing what you see and suggesting the agent
- tries a different approach. Call `send_to_task` with that nudge.
- If a second idle notification arrives for the same task after your nudge,
- escalate to the user with `escalate_to_user`.
+2. Classify what you see using the decision rules below, then act accordingly.
3. After acting, output `[agtx:idle]` on its own line and wait for the next notification.
**Important:** `escalate_to_user` shows a visible warning banner to the user in the TUI
with your reason text. Keep the reason concise (one sentence). The user will see it when
they open the task popup.
+
+---
+
+### Decision Rules
+
+#### Yes/No confirmation prompt
+
+Pattern: `[y/N]`, `[Y/n]`, `[y/n]`, `(yes/no)`, `Continue?`, `Press Enter to continue`
+
+- The **uppercase letter** is the default β€” send it.
+- `[Y/n]` β†’ send `y`
+- `[y/N]` β†’ send `n`
+- `[y/n]` (equal case) β†’ send `y`
+- "Press Enter to continue" β†’ send `""`
+
+After sending, call `read_pane_content` to confirm the prompt was dismissed.
+
+**Examples:**
+```
+Remove 14 packages? [y/N]
+β†’ send_to_task: "n"
+
+Proceed with installation? [Y/n]
+β†’ send_to_task: "y"
+
+Press Enter to continue
+β†’ send_to_task: ""
+```
+
+---
+
+#### Numbered option menu
+
+Pattern: A list of numbered options (`1)`, `2)`, etc.) with a question above.
+
+- If **one option is marked as recommended** (e.g. `(recommended)`, `[default]`, `*`,
+ `(default)`, highlighted with `>`): send that option's number.
+- If **no option is marked as recommended**: escalate to the user β€” do not guess.
+
+After sending a selection, call `read_pane_content` to confirm the prompt was dismissed.
+
+**Examples:**
+```
+? Select package manager
+ 1) npm (recommended)
+ 2) yarn
+ 3) pnpm
+β†’ send_to_task: "1"
+
+? Choose database adapter
+ 1) PostgreSQL
+ 2) MySQL
+ 3) SQLite
+β†’ escalate_to_user: "Agent is asking which database adapter to use β€” no default recommended"
+
+? Initialize git repository?
+> Yes (default)
+ No
+β†’ send_to_task: "1"
+```
+
+---
+
+#### Domain question from the agent
+
+Pattern: The agent (not a CLI tool) is asking a question that requires project knowledge,
+architectural judgment, or user preference. Indicators: the question is in prose, refers
+to the task's codebase, mentions trade-offs, or asks "Should I...", "Which approach...",
+"Do you want me to...".
+
+**Always escalate. Never answer domain questions on the user's behalf.**
+
+Call `move_task` with `action: "escalate_to_user"` and set `reason` to a one-sentence
+summary of what the agent is asking.
+
+**Examples:**
+```
+Should I split this into two separate modules or keep it in one file?
+β†’ escalate_to_user: "Agent is asking whether to split the module β€” needs user decision"
+
+I can implement this with either a REST API or GraphQL. Which do you prefer?
+β†’ escalate_to_user: "Agent is asking whether to use REST or GraphQL β€” needs user decision"
+```
+
+---
+
+#### Agent stuck on an error or in a loop
+
+Pattern: The same error message repeats, the agent is spinning, or the pane shows no
+progress despite prior nudges.
+
+- Compose a short nudge based on what you see (e.g. "The last approach failed with X.
+ Try Y instead.") and call `send_to_task`.
+- If a **second** idle notification arrives for the same task after your nudge,
+ escalate to the user with `escalate_to_user` β€” do not keep nudging indefinitely.
diff --git a/src/tui/app.rs b/src/tui/app.rs
index 4a1b46f..fde998b 100644
--- a/src/tui/app.rs
+++ b/src/tui/app.rs
@@ -4974,9 +4974,14 @@ impl App {
}
// Stuck-task notification: fire once when Planning/Running task has been Idle for 1+ min
+ // Void plugin tasks are fully user-managed β€” no stuck notifications
+ let task_plugin = self.state.board.tasks.iter()
+ .find(|t| t.id == task_status.task_id)
+ .and_then(|t| t.plugin.as_deref());
if matches!(task_status.status, TaskStatus::Planning | TaskStatus::Running)
&& phase == PhaseStatus::Idle
&& self.state.orchestrator_session.is_some()
+ && should_send_stuck_notification(task_plugin)
{
let stuck_key = format!("{}:{}", task_status.task_id, task_status.status.as_str());
if !self.state.stuck_task_notified.contains(&stuck_key) {
@@ -6232,6 +6237,12 @@ fn wait_for_prompt_trigger(tmux_ops: &Arc<dyn TmuxOperations>, target: &str, tri
false
}
+/// Returns true if a stuck-task notification should be sent for this task.
+/// Void plugin tasks are fully user-managed and never produce stuck notifications.
+fn should_send_stuck_notification(plugin_name: Option<&str>) -> bool {
+ plugin_name != Some("void")
+}
+
/// Check if the phase artifact exists for a task in its worktree.
/// Tries both zero-padded (e.g. "01") and non-padded (e.g. "1") {phase} substitution.
fn phase_artifact_exists(worktree_path: &str, status: TaskStatus, plugin: &Option<WorkflowPlugin>, cycle: i32) -> bool {
diff --git a/src/tui/app_tests.rs b/src/tui/app_tests.rs
index 0f809b5..97f3b82 100644
--- a/src/tui/app_tests.rs
+++ b/src/tui/app_tests.rs
@@ -7332,3 +7332,19 @@ fn test_switch_agent_cursor_sends_ctrl_c_not_exit() {
switch_agent_in_tmux(&mock_tmux, "proj:task", "cursor", "agent --yolo");
}
+
+#[test]
+fn test_should_send_stuck_notification_void_plugin() {
+ // Void plugin tasks must never produce stuck notifications
+ assert!(!should_send_stuck_notification(Some("void")));
+}
+
+#[test]
+fn test_should_send_stuck_notification_other_plugins() {
+ // All non-void plugins should produce stuck notifications
+ assert!(should_send_stuck_notification(Some("agtx")));
+ assert!(should_send_stuck_notification(Some("gsd")));
+ assert!(should_send_stuck_notification(Some("bmad")));
+ // No plugin set (None) should also produce notifications
+ assert!(should_send_stuck_notification(None));
+}