ππΌββοΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.
Rust adeai-agentsclaudeclaude-codecodexcursorgeminigrokopencodespec-driven-developmentvibe-codingvim
feat: improve agtx sweep and brainstorm skill and address readme (#86)
Fynn Fluegge64499d7e048d
diff --git a/README.md b/README.mdindex a4217a8..a413d56 100644--- a/README.md+++ b/README.md@@ -7,9 +7,10 @@<div align="left">> **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+>+> **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+>+> **Capture ideas without leaving your agent session** β `/agtx:brainstorm` to explore freely, `/agtx:sweep` to push the conversation to the board as tasks in one step.</div>@@ -18,6 +19,17 @@[](CONTRIBUTING.md)[](https://opensource.org/licenses/Apache-2.0)+<p align="center">+ <a href="#quick-start">Quick Start</a> β’+ <a href="#features">Features</a> β’+ <a href="#usage">Usage</a> β’+ <a href="#brainstorm--sweep-skills">Brainstorm & Sweep Skills</a> β’+ <a href="#mcp-server">MCP Server</a> β’+ <a href="#plugins">Plugins</a> β’+ <a href="#orchestrator-agent-experimental">Orchestrator</a> β’+ <a href="#configuration">Configuration</a>+</p>+---<img width="840" src="https://github.com/user-attachments/assets/45858e09-ab61-422b-b708-db060c73a900" />@@ -36,6 +48,8 @@AI coding tools give you one agent, one task, one terminal. agtx gives you a **kanban board where multiple coding agents work in parallel** β each in its own git worktree, each in its own tmux window, running autonomously through a spec-driven workflow managed by an orchestrator agent.+When ideas come up mid-session, `/agtx:brainstorm` keeps your agent in exploration mode β then `/agtx:sweep` turns the conversation into board tasks with a single confirmation step. **No context switching, no copy-pasting β ideas flow directly into work.**+With the orchestrator, you don't even manage the board yourself. **An AI agent picks up tasks, delegates work, and ensures getting things done** through planning, implementation, review and resolving conflicts β while you focus on what matters: research, defining tasks, and merging changes.> [!TIP]@@ -44,6 +58,7 @@ With the orchestrator, you don't even manage the board yourself. **An AI agent p## Features- **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))+- **Brainstorm & Sweep skills**: Capture ideas and push them to the board from any coding agent session β `/agtx:brainstorm` to explore freely, `/agtx:sweep` to decompose and create tasks with one confirmation step ([details](#brainstorm--sweep-skills))- **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 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@@ -81,7 +96,6 @@ agtx --experimentalcargo build --releasecp target/release/agtx ~/.local/bin/```-</details>### Requirements@@ -90,7 +104,8 @@ cp target/release/agtx ~/.local/bin/## Usage-### Keyboard Shortcuts+<details>+<summary><strong>Keyboard Shortcuts</strong></summary>| Key | Action ||-----|--------|@@ -99,6 +114,7 @@ cp target/release/agtx ~/.local/bin/| `o` | Create new task || `R` | Enter research mode || `β©` | Open task (view agent session) |+| `Ctrl+f` | Fullscreen attach to task's tmux session || `m` | Move task forward in workflow || `r` | Resume task (Review β Running) / Move back (Running β Planning) || `p` | Next phase (Review β Planning, cyclic plugins only) |@@ -110,7 +126,10 @@ cp target/release/agtx ~/.local/bin/| `e` | Toggle project sidebar || `q` | Quit |-### Task Creation Wizard+</details>++<details>+<summary><strong>Task Creation Wizard</strong></summary>Press `o` to create a new task. The wizard guides you through:1. **Title** β enter a short task name@@ -119,7 +138,10 @@ Press `o` to create a new task. The wizard guides you through:The agent is configured at the project level via `config.toml` (not per-task).-### Task Description Editor+</details>++<details>+<summary><strong>Task Description Editor</strong></summary>When writing a task description, you can reference files, skills, and other tasks inline:@@ -129,13 +151,112 @@ When writing a task description, you can reference files, skills, and other task| `/` | Fuzzy search and insert an agent skill/command (at line start or after space) || `!` | Fuzzy search and insert a task reference (at line start or after space) |+</details>++### Agent Sessions++Each task runs in its own tmux window with a dedicated coding agent. The session persists across the entire task lifecycle β you can open the task popup at any time to see live agent output, or press `Ctrl+f` to attach fullscreen.++- **Persistent context**: The agent's full conversation history is preserved across Planning β Running β Review+- **Resume from Review**: Moving a task back to Running simply reconnects to the existing session β no re-initialization needed+- **Inline view**: Press `β©` on any active task to open a scrollable tmux view inside the TUI+- **Fullscreen**: Press `Ctrl+f` to attach directly to the agent's tmux window+- **Auto merge-conflict resolution**: When a Review task becomes idle, agtx checks for merge conflicts with the default branch using a non-destructive virtual merge (`git merge-tree`). If conflicts are detected, the agent is automatically sent the `/agtx:merge-conflicts` skill to resolve them and re-commit++## Brainstorm & Sweep Skills++Two companion skills for capturing ideas in any coding agent session and turning them into tasks in the agtx board.++| Skill | Command | When to use |+|-------|---------|-------------|+| **Brainstorm** | `/agtx:brainstorm` | Explore a feature idea β discussion only, no planning or implementation |+| **Sweep** | `/agtx:sweep` | Push conversation outcomes to the agtx board as tasks |++**Typical flow:**+```+/agtx:brainstorm β explore the idea freely+ β+/agtx:sweep β extract tasks, confirm, push to board+ β+agtx board β tasks appear in Backlog, ready to advance+```++The brainstorm skill keeps the agent in discussion mode β asking questions, surfacing trade-offs, no code or plans. When the conversation feels complete, run `/agtx:sweep` to decompose outcomes into feature-level tasks and push them to the board with a single confirmation step.++### Install++<details>+<summary><strong>Claude Code</strong></summary>++```bash+claude plugin marketplace add fynnfluegge/agtx+claude plugin install agtx@agtx-marketplace+claude mcp add --scope user agtx -- agtx mcp-serve+```++</details>++<details>+<summary><strong>Codex</strong></summary>++```bash+codex mcp add agtx -- agtx mcp-serve+```++Add to your project's `.agents/plugins/marketplace.json`:+```json+{+ "name": "local-repo",+ "plugins": [+ {+ "name": "agtx",+ "source": {+ "source": "local",+ "path": "./plugins/agtx"+ },+ "policy": {+ "installation": "AVAILABLE",+ "authentication": "ON_INSTALL"+ },+ "category": "Productivity"+ }+ ]+}+```++Then in any Codex session: `@agtx:sweep` / `@agtx:brainstorm`++</details>++<details>+<summary><strong>Gemini CLI</strong></summary>++```bash+gemini mcp add agtx -- agtx mcp-serve+echo "@skills/sweep/SKILL.md" >> ~/GEMINI.md+```++</details>++<details>+<summary><strong>Cursor</strong></summary>-### Agent Session Features+```bash+cursor mcp add agtx -- agtx mcp-serve+cp skills/sweep/SKILL.md ~/.cursor/rules/agtx-sweep.md+```++</details>-- Sessions automatically resume when moving Review β Running-- Full conversation context is preserved across the task lifecycle-- View live agent output in the task popup-- **Auto merge-conflict resolution**: When a Review task becomes idle, agtx checks for merge conflicts with the default branch. If conflicts are detected, the agent is automatically instructed to resolve them.+<details>+<summary><strong>Other</strong></summary>++Register `agtx mcp-serve` as an MCP server, then copy `skills/sweep/SKILL.md` into your agent's context.++</details>++> [!NOTE]+> The project must have been opened in agtx at least once to appear in `list_projects`. Run `agtx` in your project directory first.## Configuration@@ -436,11 +557,42 @@ tmux -L agtx attach### Data Storage-- **Database**: `~/Library/Application Support/agtx/` (macOS) or `~/.local/share/agtx/` (Linux)+- **Database**: `~/Library/Application Support/agtx/` (macOS) or `~/.config/agtx/` (Linux)- Config: `~/.config/agtx/config.toml`- **Worktrees**: `.agtx/worktrees/` in each project- **Tmux**: Dedicated server `agtx` with per-project sessions+## MCP Server++The agtx MCP server (`agtx mcp-serve`) exposes the board to any coding agent session via the [Model Context Protocol](https://modelcontextprotocol.io). Used by the orchestrator agent and the brainstorm & sweep skills.++### Modes++| Mode | Command | Used by |+|------|---------|---------|+| **Global** | `agtx mcp-serve` | Sweep/brainstorm skills β works across all projects |+| **Project-scoped** | `agtx mcp-serve <path>` | Orchestrator β bound to one project at startup |++In global mode all tools require a `project_id` parameter. Call `list_projects` first to resolve it.++### Tools++| Tool | Description |+|------|-------------|+| `list_projects` | List all projects indexed in agtx |+| `list_tasks` | List tasks, optionally filtered by status |+| `get_task` | Get task details + `allowed_actions` for valid transitions |+| `create_task` | Create a single backlog task |+| `create_tasks_batch` | Batch-create tasks with index-based dependencies |+| `update_task` | Modify a backlog task (title, description, deps) |+| `delete_task` | Delete a backlog task |+| `move_task` | Queue a phase transition |+| `get_transition_status` | Check if a queued transition completed or errored |+| `check_conflicts` | Non-destructive merge conflict check against default branch |+| `get_notifications` | Fetch pending orchestrator notifications |+| `read_pane_content` | Read the last N lines of a task's tmux pane |+| `send_to_task` | Send a message to a task's agent pane |+## Orchestrator Agent (Experimental)> Press `O` and walk away. Come back to changes ready to merge.@@ -475,19 +627,6 @@ The orchestrator communicates with agtx through the [Model Context Protocol (MCPββββββββββββββββ```-**MCP tools available to the orchestrator:**--| Tool | Description |-|------|-------------|-| `list_tasks` | List all tasks, optionally filtered by status |-| `get_task` | Get task details including `allowed_actions` for valid transitions |-| `move_task` | Queue a state transition (the TUI executes it with full side effects) |-| `get_transition_status` | Check if a queued transition completed or errored |-| `check_conflicts` | Non-destructive merge conflict detection against the default branch |-| `get_notifications` | Manually fetch pending notifications (backup β usually pushed automatically) |-| `read_pane_content` | Read the last N lines of a task's agent tmux pane |-| `send_to_task` | Send a message to a task's agent pane (Planning/Running only) |-**How it works:**1. When you press `O`, the TUI registers the MCP server with the orchestrator agent via `claude mcp add-json --scope local`2. The orchestrator receives phase completion notifications pushed to its tmux pane when idle@@ -497,143 +636,6 @@ The orchestrator communicates with agtx through the [Model Context Protocol (MCP6. Escalated tasks show a `β ` badge on the kanban board; opening the task popup shows the reason and dismisses the flag7. MCP registration is cleaned up when the orchestrator is stopped-## Brainstorm & Sweep--Two companion skills for capturing ideas and turning them into tasks.--| Skill | Command | When to use |-|-------|---------|-------------|-| **Brainstorm** | `/agtx:brainstorm` | Explore a feature idea β discussion only, no planning or implementation |-| **Sweep** | `/agtx:sweep` | Push conversation outcomes to the agtx board as tasks |--**Typical flow:**-```-/agtx:brainstorm β explore the idea freely- β-/agtx:sweep β extract tasks, confirm, push to board- β-agtx board β tasks appear in Backlog, ready to plan-```--The brainstorm skill keeps the agent in discussion mode β asking questions, surfacing trade-offs, no code or plans. When the conversation feels complete, run `/agtx:sweep` to decompose outcomes into feature-level tasks and push them to the board with a single confirmation step.--### Install--<details>-<summary><b>Claude Code (recommended)</b></summary>--**Install via plugin marketplace** (two steps β adds the marketplace, then installs):-```-/plugin marketplace add fynnfluegge/agtx-/plugin install agtx@agtx-marketplace-```--This registers the MCP server automatically. Then in any Claude Code session:-```-/agtx:sweep-```--**Manual install** (if you prefer):-```bash-claude mcp add agtx -- agtx mcp-serve-```--Then copy the skill to Claude's command discovery path:-```bash-mkdir -p ~/.claude/commands/agtx-cp skills/sweep/SKILL.md ~/.claude/commands/agtx/sweep.md-```--</details>--<details>-<summary><b>Gemini CLI</b></summary>--Add the skill to your `GEMINI.md` for persistent context:-```bash-echo "@~/skills/sweep/SKILL.md" >> ~/GEMINI.md-```--Register the global MCP server in your Gemini config:-```bash-gemini mcp add agtx -- agtx mcp-serve-```--Then in any Gemini session:-```-/agtx-sweep-```--</details>--<details>-<summary><b>Cursor</b></summary>--Copy the skill into your Cursor rules:-```bash-cp skills/sweep/SKILL.md ~/.cursor/rules/agtx-sweep.md-```--Register the MCP server in Cursor's MCP settings (`~/.cursor/mcp.json`):-```json-{- "mcpServers": {- "agtx": {- "command": "agtx",- "args": ["mcp-serve"]- }- }-}-```--</details>--<details>-<summary><b>Codex</b></summary>--**Install via repo marketplace** β add to your project's `.agents/plugins/marketplace.json`:-```json-{- "name": "local-repo",- "plugins": [- {- "name": "agtx",- "source": {- "source": "local",- "path": "./plugins/agtx"- },- "policy": {- "installation": "AVAILABLE",- "authentication": "ON_INSTALL"- },- "category": "Productivity"- }- ]-}-```--Then in any Codex session:-```-@agtx:sweep-@agtx:brainstorm-```--</details>--<details>-<summary><b>Other agents</b></summary>--Skills are plain Markdown β they work with any agent that accepts instruction files. Copy `skills/sweep/SKILL.md` into your agent's context and register the MCP server:--```bash-agtx mcp-serve # global mode β works from any directory-```--</details>--> [!NOTE]-> The project must have been opened in agtx at least once to appear in `list_projects`. Run `agtx` in your project directory first.-## ContributingContributions are welcome! Whether it's a bug fix, new plugin, agent integration, or documentation improvement.diff --git a/skills/sweep/SKILL.md b/skills/sweep/SKILL.mdindex 31f24c6..2e503b4 100644--- a/skills/sweep/SKILL.md+++ b/skills/sweep/SKILL.md@@ -107,18 +107,23 @@ When the user asks to sweep, push, or hand off the conversation to the board:2. Call `list_tasks` with `project_id` β check for duplicates3. Extract every actionable work item from the conversation4. **Stop and present the proposed task list to the user. Do NOT call any MCP write tools yet.**- Show title, description, and dependencies for each task:+ Show each task with a checkmark, title, description, and dependencies:```- [0] Add streaming CSV export endpoint- Implement GET /export/csv with streaming response- depends on: none- [1] Add date range filter to export- Query params ?from=&to= applied before streaming- depends on: [0]+ β [0] Add streaming CSV export endpoint+ Implement GET /export/csv with streaming response+ depends on: none++ β [1] Add date range filter to export+ Query params ?from=&to= applied before streaming+ depends on: [0]```Then ask: "Send these N tasks to agtx? (yes / edit / cancel)"-5. **Only after explicit user confirmation:** use `create_tasks_batch` (with `project_id`) for multiple tasks, `create_task` for one-6. Report created IDs:+5. **Handle the response:**+ - `yes` β proceed with all tasks+ - `edit` β ask which task to modify and what to change, update it in the list, re-show the full list, ask to confirm again+ - `cancel` β stop, do nothing+6. **Only after final confirmation:** use `create_tasks_batch` (with `project_id`) for multiple tasks, `create_task` for one+7. Report created IDs:```β a1b2c3 Add streaming CSV export endpointβ d4e5f6 Add date range filter to export