YbotBot - AI Guild Implementation Tool

YbotBot is a command-line tool that implements the AI Guild methodology, enabling structured collaboration between AI agents and human developers. It provides a configurable framework for managing AI agent behaviors through customizable playbooks that define commands, roles, and workflow handoffs.

🚀 Features

• Modular Configuration System: Organize AI behaviors into commands, roles, and handoffs
• Multi-level Customization: Support for default, modified, and user-defined configurations
• JIRA Integration: Built-in support for JIRA ticket tracking and workflow management
• Flexible Playbook System: Markdown-based playbooks for easy editing and version control
• Tool Integration: Configurable support for testing frameworks, CI/CD, and development tools
• Interactive Setup: Guided configuration process for quick project initialization

📦 Installation

Global Installation (Recommended)

npm install -g @hdtsllc/ybotbot

Local Installation

npm install @hdtsllc/ybotbot

🔧 Quick Start

1. Initialize your project:

   ybot setup

   This interactive setup will:

   • Configure your playbook preferences (default/modified/custom)
   • Set up JIRA integration (optional)
   • Configure tool integrations
   • Create .ybotbot/ directory with your configuration files

2. Build your guild file:

   ybot build

   This will concatenate your configured playbooks into a single guild file.

📚 Configuration

Directory Structure

your-project/
├── .ybotbot/
│   ├── user-config.ini      # User configuration
│   ├── ybot-features.json   # Build configuration
│   └── guild-output.md      # Generated guild file
├── playbooks/
│   ├── internal/            # Default playbooks
│   │   ├── COMMANDS-DEF.md
│   │   ├── ROLES-DEF.md
│   │   └── HANDOFFS-DEF.md
│   └── modified/            # Modified versions
│       ├── COMMANDS-MOD.md
│       ├── ROLES-MOD.md
│       └── HANDOFFS-MOD.md
└── custom/                  # Your custom playbooks

Configuration Options

Playbook Configuration

During setup, you can choose for each component (Commands, Roles, Handoffs):

• Default (Ybot): Use built-in playbooks
• Modified: Use modified versions from the modified folder
• User: Specify custom file paths

JIRA Integration

Configure JIRA integration:

• Method: MCP (Model Context Protocol)
• Setup: Simple Yes/No during configuration
• Usage: Specify cloudId and project key in MCP function calls

Tool Integration

Enable/disable various development tools:

• Cypress (E2E Testing)
• Jest (Unit Testing)
• Docker
• GitHub Actions
• Jenkins
• And more...

Custom File Configuration

The .ybotbot/user-config.ini file allows you to include custom files in your builds. Any file paths added to the following sections will automatically be included in the build process:

[User File/path Configuration]
userCommands='./commands.md'          # Custom commands documentation
userRoles='./my-roles.md'             # Custom roles definitions
userHandoffs='./workflows.md'         # Custom handoff patterns
userUnitTesting='./unit-test-guide.md'
userE2ETesting='./e2e-guide.md'
userCICD='./cicd-setup.md'
userEnvironments='./env-config.md'

[application playbooks]
applctionDescrition='./app-description.md'
applctionGoals='./project-goals.md'

How it works:

1. Add file paths to any field in the configuration
2. Run ybot setup and select which files to include
3. Selected files will be automatically added to your build
4. Files appear in the generated CLAUDE.md or .ybotbot/applicationPlaybook.md

Example: If you set userCommands='./my-custom-commands.md', this file will be included in your guild playbook build when selected during setup.

🎯 Core Concepts

Commands

Define the directives that AI agents can understand and execute:

• START - Initialize session
• LIST - List items or resources
• READ - Read files or documentation
• WhatsUp - Summarize current context
• Status - Check project status
• SNR - Summarize, Next Steps, Request Role

Roles

Different operational modes for AI agents:

• 🪞 Mirror Mode - Confirm understanding
• 🧭 Scout Mode - Research and explore
• 🤔 Architect Mode - Design solutions
• 🧰 Builder Mode - Generate code
• 📦 Package Mode - Finalize and deploy
• And many more specialized roles...

Handoffs

Structured workflow transitions between roles following the classic lifecycle:

MIRROR → SCOUT → ARCHITECT → CRK → BUILDER → PACKAGE

📝 Usage Examples

Basic Setup and Build

# Set up a new project with default configurations
ybot setup

# Build the guild file
ybot build

Custom Configuration

Edit .ybotbot/user-config.ini to customize:

[Commands]
user_path = ./my-custom-commands.md

[Roles]
user_path = ./team-specific-roles.md

[JIRA]
enabled = true
method = API
project_key = MYPROJ

CI/CD Integration

# GitHub Actions example
- name: Build AI Guild Configuration
  run: |
    npm install -g @hdtsllc/ybotbot
    ybot build

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the ISC License.

🔗 Links

• NPM Package
• GitHub Repository
• AI Guild Documentation

💡 Tips

• Start with default configurations and gradually customize as needed
• Use the modified folder for team-specific adjustments
• Keep your custom playbooks in version control
• Regular ybot build ensures your guild file stays up-to-date
• Integrate with your CI/CD pipeline for automated guild file generation

Built with ❤️ for better AI-human collaboration in software development.