dotfiles

This MCP server acts as the orchestration layer for managing AI agent workflows across multiple harnesses. It centralizes agent configuration in a single reusable config (an .agent-config.yml file) and enforces reproducible procedures via the commands directory (commands/), which contains archetypal workflows such as /close-issue, /create-issue, /extract-best-frame, and /retro. The system is designed to be harness-agnostic, so you can drive tasks across Claude Code, Amazon Q, Codex, or other providers without duplicating logic. You can also leverage the OpenTelemetry-enabled observability stack to monitor performance and throughput as you scale up parallel agent execution using tmux and git worktrees for organizing multiple concurrent tasks. To start using it, run the MCP server (via the provided start-mcp.sh) and ensure your global configuration (in .agent-config.yml) aligns with your preferred harnesses and agent settings. The modular approach also means you can load individual shell modules from .bash_aliases.d to tailor your environment for this MCP workflow without cluttering your global shell. The overall goal is to achieve high-throughput, reproducible agent orchestration with self-healing capabilities and principled enforcement across your development stack.

Prerequisites:

• Git installed on your machine
• A POSIX-compliant shell (bash) available
• Basic familiarity with the repository structure (commands/, knowledge/, and .agent-config.yml)

Step-by-step:

1. Clone the repository: git clone https://github.com/atxtechbro-dotfiles/dotfiles.git cd dotfiles

2. Review prerequisites and environment setup:

   • Ensure your shell loads modular aliases from ~/.bash_aliases.d
   • Confirm you have a valid .agent-config.yml at the repository root or a path you will reference in MCP_CONFIG_PATH

3. Install any required runtime tools (if applicable):

   • If the MCP server is driven by a bash script in this repo, no additional package manager is required beyond Git and bash
   • If you expect a specific toolchain (e.g., Python, Node) per your environment, install those separately as needed

4. Start the MCP server: ./start-mcp.sh

5. Validate operation:

   • Check logs produced by the MCP server
   • Ensure commands in commands/ directory can be invoked and perform as expected with your harnesses

Note: This setup assumes a shell-based orchestration flow. If a different runtime (Node/Python) is preferred in your environment, adjust the start script or the command in mcp_config accordingly.

Tips and common issues:

• The system emphasizes reproducible configuration (Spilled Coffee Principle). Avoid manual terminal heroics; encode state-changing actions in scripts and setup files.
• The modular shell configuration pattern loads tool-specific alias files automatically if they exist, keeping your environment clean and extensible.
• Global-first configuration is encouraged: default to global settings unless you have a compelling local exception.
• If you encounter issues with agent throughput, review the throughput-definition and observability docs referenced in the README to identify bottlenecks and adjust your tmux worktrees or parallel task strategies.
• The .agent-config.yml (and the knowledge/procedures directories) are automatically loaded into agent context to maintain consistency across harnesses; ensure these are kept up to date when adding new tools or workflows.