ππΌββοΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.
Rust adeai-agentsclaudeclaude-codecodexcursorgeminigrokopencodespec-driven-developmentvibe-codingvim
docs: add contribution section (#38)
Fynn FlΓΌgge709bf2d33952
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 0000000..bf65657--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,115 @@+# Contributing++Thanks for your interest in contributing to agtx! This guide will help you get started.++New here? Issues labeled [`good first issue`](https://github.com/fynnfluegge/agtx/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) are a great place to start β they're scoped, well-described, and a perfect way to get familiar with the codebase.++## Getting Started++### Prerequisites++- **Rust** 1.70+ ([install](https://rustup.rs))+- **tmux** (runtime dependency for agent sessions)+- **git** (runtime dependency for worktrees)+- **gh** CLI (optional, for PR operations)++### Setup++```bash+git clone https://github.com/fynnfluegge/agtx+cd agtx+cargo build+cargo test --features test-mocks+```++### Running Locally++```bash+# Run in any git repository+cd agtx && cargo run --manifest-path /path/to/agtx/Cargo.toml++# Or build and copy to PATH+cargo build --release+cp target/release/agtx ~/.local/bin/+```++## Ways to Contribute++### Bug Reports++Open an [issue](https://github.com/fynnfluegge/agtx/issues) with:+- What you expected vs. what happened+- Steps to reproduce+- OS, terminal emulator, and agent CLI versions++### Write a Plugin++Plugins are the easiest way to contribute. A single `plugin.toml` defines an entire workflow. See the [plugin reference](README.md#plugins) in the README.++Place your plugin in `plugins/<name>/plugin.toml` and open a PR. Check the existing plugins for examples:+- `plugins/void/plugin.toml` β simplest possible plugin+- `plugins/agtx/plugin.toml` β full-featured with skills and prompts+- `plugins/gsd/plugin.toml` β cyclic workflow with preresearch++### Add Agent Support++To add a new AI coding CLI:++1. Add to `known_agents()` in `src/agent/mod.rs`+2. Add `build_interactive_command()` match arm in `src/agent/mod.rs`+3. Add agent-native skill directory in `agent_native_skill_dir()` in `src/skills.rs`+4. Add plugin command transform in `transform_plugin_command()` in `src/skills.rs`++### Code Changes++1. Fork the repository+2. Create a feature branch: `git checkout -b my-feature`+3. Make your changes+4. Run tests: `cargo test --features test-mocks`+5. Open a pull request against `main`++## Architecture Overview++See [CLAUDE.md](CLAUDE.md) for the full architecture documentation, including:+- Module structure and key files+- Task workflow lifecycle+- Plugin system internals+- Agent integration patterns+- Testing patterns (mock traits, feature flags)++### Key Directories++```+src/tui/ β TUI rendering and input handling+src/db/ β SQLite database (tasks, projects)+src/tmux/ β Tmux server management+src/git/ β Git worktree operations+src/agent/ β Agent detection, spawning, switching+src/mcp/ β MCP server for orchestrator+src/config/ β Configuration and plugin loading+plugins/ β Bundled workflow plugins+skills/ β Built-in skill files (embedded at compile time)+```++### Testing++```bash+# Run all tests+cargo test --features test-mocks++# Run a specific test+cargo test --features test-mocks test_name+```++Tests use mock traits (`TmuxOperations`, `GitOperations`, `AgentOperations`) behind the `test-mocks` feature flag. Pure function tests don't need the feature flag.++## Code Style++- Follow existing patterns in the codebase+- Use `anyhow::Result` for fallible functions with `.context()` for error messages+- Keep UI state in `AppState`, drawing functions are static+- Add tests for new functionality++## License++By contributing, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE).diff --git a/README.md b/README.mdindex 8aad251..be2f9cc 100644--- a/README.md+++ b/README.md@@ -3,13 +3,20 @@[//]: <img src="https://github.com/user-attachments/assets/54ac039b-085e-490b-aacc-36c8e244e313" width="428" /># agtx-#### An AI agent that manages other coding agents in a terminal kanban board-Let different AI coding agents collaborate on the same task, e.g.-**Gemini β research** | **Claude β implement** | **Codex β review**+<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**-Add tasks. Press one key. An orchestrator agent picks it up, plans, and delegates<br/>-to multiple coding agents running in parallel. Come back to changes ready to merge.+</div>++[](https://github.com/fynnfluegge/agtx/actions/workflows/ci.yml)+[](https://github.com/fynnfluegge/agtx/releases)+[](CONTRIBUTING.md)+[](https://opensource.org/licenses/Apache-2.0)<br/>@@ -31,6 +38,9 @@ AI coding tools give you one agent, one task, one terminal. agtx gives you a **kWith 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]+> Check out the [Contributing](#contributing) section or have a look at [`good first issues`](https://github.com/fynnfluegge/agtx/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to get involved and become a contributor βοΈ+## 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))@@ -453,9 +463,33 @@ The orchestrator communicates with agtx through the [Model Context Protocol (MCP4. The TUI processes the transition request, executes all side effects (agent switching, skill deployment, prompt sending), and updates the database5. MCP registration is cleaned up when the orchestrator is stopped+## Contributing++Contributions are welcome! Whether it's a bug fix, new plugin, agent integration, or documentation improvement.++See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide. Here's the short version:++```bash+# Fork & clone+git clone https://github.com/<you>/agtx && cd agtx++# Build & test+cargo build && cargo test --features test-mocks+```++### Good First Contributions++Not sure where to start? Here are some ideas:++- **Write a plugin** β A single `plugin.toml` is all you need. See [Creating a Plugin](#plugins) for the full reference+- **Add a new agent** β Integrate your favorite AI coding CLI. See the [architecture docs](CLAUDE.md) for how agents are structured+- **Improve documentation** β Found something unclear? Help others by improving it+- **Report bugs** β Open an [issue](https://github.com/fynnfluegge/agtx/issues). Reproduction steps are always appreciated+- **Browse open issues** β Check the [`good first issue`](https://github.com/fynnfluegge/agtx/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label for beginner-friendly tasks+## Development-See [CLAUDE.md](CLAUDE.md) for development documentation.+See [CLAUDE.md](CLAUDE.md) for full architecture docs and development patterns.```bash# Build