Repolode
Submit
tiagovilasboas

tiagovilasboas/grok-bot-architecture

An MIT reference architecture for organizing AI agent teams with reusable role skills, MCP connectors, and human approval gates.

View on GitHub
Stars
50
Forks
11
Open issues
0
Last commit
10 days ago

What is it?

This repository is a model- and framework-independent reference for structuring a team of AI agents. A chief-of-staff agent turns goals into scoped assignments and dispatches them to specialists such as engineering, publishing, security, inbox triage, and career screening. Each role is defined by a reusable SKILL.md recipe and works through host-enforced tool permissions rather than ambient access.

The core idea is human-in-the-loop approval. Privileged actions produce a request that waits for an authenticated decision bound to the exact action and revision, and a timeout defaults to waiting rather than proceeding. Typed handoff records and a Markdown board carry assignments and evidence between roles, and the repository includes JSON validators, board tooling, and a bounded local approval lifecycle example.

The project also documents how to map this pattern onto Grok Bot, with setup steps, approval policy guidance, and a walkthrough. It does not contain the Grok Bot product's source code and is not affiliated with xAI.

Key features

  • 01Chief-of-staff agent that scopes, assigns and reviews work for specialist roles
  • 02Nine reusable role skills defined as SKILL.md recipes
  • 03Approval gates that bind each decision to an exact action revision and wait on timeout
  • 04Typed handoff records and a Markdown board for sharing state and evidence
  • 05JSON validators and a local approval lifecycle example with no external dependencies

Use cases

  • Designing a team of persistent AI assistants that each handle a separate domain like email and code
  • Adding human approval before an agent sends messages, merges code, or changes external systems
  • Mapping role-based permissions and handoffs onto an existing agent host
  • Learning trust-boundary patterns for agent systems before writing production code

Quick start

  1. 1

    Clone the repository

    git clone https://github.com/tiagovilasboas/grok-bot-architecture.git
  2. 2

    Enter the project folder

    cd grok-bot-architecture
  3. 3

    Run the local validation and approval lifecycle check

    bash scripts/check.sh

Things to know

  • This is a reference architecture and documentation pattern, not a standalone runtime agent system.
  • The Grok Bot setup path depends on a separate Grok Bot product whose source code is not included.
  • The validators check file shapes only and do not authenticate human approvers or execute side effects.

In collections

Multi-agent orchestration frameworksOpen-source AI agent frameworks & appsMCP serversOpen-source personal AI agents

Topics

#ai-agents#multi-agent#mcp#human-in-the-loop#agent-architecture#approval-workflow#personal-agent#agentic-ai#architecture#desktop-agents

FAQ

What is grok-bot-architecture?
An MIT reference architecture for organizing AI agent teams with reusable role skills, MCP connectors, and human approval gates. This repository is a model- and framework-independent reference for structuring a team of AI agents. A chief-of-staff agent turns goals into scoped assignments and dispatches them to specialists such as engineering, publishing, security, inbox triage, and career screening. Each role is defined by a reusable SKILL.md recipe and works through host-enforced tool permissions rather than ambient access.
Is grok-bot-architecture free to use? What license does it have?
grok-bot-architecture is open source under the MIT license. Check the license terms before using it in commercial products.
Is grok-bot-architecture still maintained?
Actively maintained. The last commit to grok-bot-architecture was on Oct 29, 2026.
What can I use grok-bot-architecture for?
Designing a team of persistent AI assistants that each handle a separate domain like email and code Adding human approval before an agent sends messages, merges code, or changes external systems Mapping role-based permissions and handoffs onto an existing agent host Learning trust-boundary patterns for agent systems before writing production code
How do I install grok-bot-architecture?
Clone the repository: git clone https://github.com/tiagovilasboas/grok-bot-architecture.git Enter the project folder: cd grok-bot-architecture Run the local validation and approval lifecycle check: bash scripts/check.sh
Where can I get grok-bot-architecture?
The source code and installation instructions are on GitHub: https://github.com/tiagovilasboas/grok-bot-architecture

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects