mbstools

mbscode

An agentic development framework with mandatory gates, autonomous review loops, and per-project hooks. Works with Claude Code, Copilot CLI, Codex/OpenCode, and Cursor.

What It Does

mbscode enforces disciplined development through:

• Mandatory gates -- Pre-task and post-task checks that cannot be skipped
• Autonomous review loops -- Multi-dimensional code review that iterates without human interaction until all criteria pass
• Per-project hooks -- Configurable lifecycle hooks via markdown files
• Skill-based workflows -- Brainstorming, planning, execution, and verification pipeline
• Cross-platform consistency -- Same behavior regardless of which AI coding tool you use

Installation

Claude Code (Plugin)

# Step 1: Add the marketplace
/plugin marketplace add mbstools/mbscode

# Step 2: Install the plugin
/plugin install mbscode@mbscode

Alternative -- local installation:

git clone https://github.com/mbstools/mbscode.git .mbscode
/plugin install .mbscode

Claude Code auto-bootstraps via the SessionStart hook -- no manual setup needed.

Copilot CLI

1. Clone into your project:

   git clone https://github.com/mbstools/mbscode.git .mbscode
   

2. Copy the bootstrap file to your project:

   mkdir -p .github
   cp .mbscode/.github/copilot-instructions.md .github/copilot-instructions.md
   

3. Update skill paths in .github/copilot-instructions.md to use .mbscode/ prefix (e.g., skills/brainstorming/SKILL.md → .mbscode/skills/brainstorming/SKILL.md).

Cursor

1. Clone into your project:

   git clone https://github.com/mbstools/mbscode.git .mbscode
   

2. Copy the bootstrap file to your project root:

   cp .mbscode/.cursorrules .cursorrules
   

3. Update skill paths in .cursorrules to use .mbscode/ prefix.

Codex / OpenCode

1. Clone into your project:

   git clone https://github.com/mbstools/mbscode.git .mbscode
   

2. Copy the bootstrap file to your project root:

   cp .mbscode/AGENTS.md AGENTS.md
   

3. Update skill paths in AGENTS.md to use .mbscode/ prefix.

First Run

On the first session, the agent detects that GATES.md is missing and runs Project Initialization automatically. This creates:

• GATES.md -- Quality gates (customize the Custom Gates section)
• HOOKS.md -- Lifecycle hooks (customize pre/post-task actions)
• PROJECT.md -- Project identity (tech stack, commands, architecture)
• MAP.md -- File index (every file with one-line purpose)
• SESSION.md -- Session state (current work, what's next)
• CONVENTIONS.md -- Coding standards (commit format, branch naming, style)
• LESSONS_LEARNED.md -- Mistake log (grows organically)

Project Structure

mbscode/
├── .claude-plugin/      # Claude Code plugin manifest + marketplace
│   ├── marketplace.json
│   └── plugin.json
├── .github/             # Copilot CLI bootstrap
│   └── copilot-instructions.md
├── agents/              # Agent definitions
│   └── code-reviewer.md # 6-dimension pre-merge review agent
├── commands/            # Skill stubs (required for Claude Code skill discovery)
├── docs/
│   ├── ARCHITECTURE.md  # Complete architecture reference
│   └── plans/           # User plan files (empty by default)
│       └── .gitkeep
├── hooks/               # Lifecycle hooks
│   ├── hooks.json       # Hook configuration (maps events to commands)
│   ├── session-start    # SessionStart hook (bash)
│   ├── session-start.ps1 # SessionStart hook (PowerShell)
│   └── run-hook.cmd     # Cross-platform polyglot hook launcher (bash + Windows)
├── scripts/             # Framework validation
│   ├── validate-consistency.sh
│   └── validate-consistency.ps1
├── skills/              # 12 core skills
│   ├── using-mbscode/   # Bootstrap: manifest, task classification, gate enforcement
│   ├── brainstorming/   # Structured design exploration
│   ├── writing-plans/   # Plan creation with milestones and resume sections
│   ├── executing-plans/ # Inline execution with gate checks
│   ├── subagent-driven-development/ # Parallel subagent dispatch
│   ├── autonomous-review/           # Iterative review loop (5 dimensions)
│   ├── verification-before-completion/ # Evidence-based completion checks
│   ├── systematic-debugging/        # Hypothesis-driven debugging
│   ├── project-documentation/       # Navigation file management
│   ├── finishing-a-development-branch/ # Branch completion and PR workflow
│   ├── test-driven-development/     # TDD strategy and test design
│   └── writing-skills/              # Guide for authoring new skills
├── .gitattributes       # Line ending and diff settings
├── .gitignore           # Ignored files
├── GATES.md             # Default gate template (copied during init)
├── HOOKS.md             # Default hook template (copied during init)
├── CLAUDE.md            # Claude Code bootstrap