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
├── .cursorrules         # Cursor bootstrap
├── AGENTS.md            # Codex/OpenCode bootstrap
├── LICENSE              # MIT
└── README.md

How Gates Work

Gates are mandatory checks the agent must pass before starting and after completing any task. They cannot be rationalized away.

Pre-Task Gates (5 checks):

• Plan exists for multi-step tasks
• Feature branch created
• Requirements understood
• Existing patterns studied
• Scope is atomic

Post-Task Gates (16 checks):

• Tests pass with evidence
• No dead code, no magic numbers
• DRY (name the duplicated patterns)
• Simplest solution (name what you'd remove)
• Root cause addressed (state why this is the cause)
• Error paths handled (list them)
• ...and more

Custom Gates: Add project-specific rules in the Custom Gates section of your project's GATES.md:

## Custom Gates
- [ ] All API endpoints have rate limiting
- [ ] Database migrations are reversible
- [ ] No debug logging in production code

How Hooks Work

HOOKS.md defines lifecycle actions the agent runs at specific points:

Hook	When	Purpose
Pre-Task	Before starting work	Read gates, check git status
Post-Task	After completing work	Run tests, lint, verify gates
Milestone	After major completions	Run autonomous review loop

Customize by editing your project's HOOKS.md.

Autonomous Review Loop

After milestones, the review loop runs without human interaction:

1. Optimization -- Is this efficient?
2. Simplicity -- Is this the simplest implementation?
3. Modularity -- Can each unit be understood independently?
4. Extensibility -- Can features be added without modifying existing code?
5. Security -- Are inputs validated, secrets excluded, errors safe?

Each dimension is checked. If any fails: fix, re-check. Loop continues until ALL pass (max 3 iterations per dimension).

Skill Workflow

Brainstorming --> Writing Plans --> Executing Plans --> Autonomous Review
     |                |                 |                     |
  Design doc      Plan doc       Gate-enforced         Multi-dimensional
  approved        approved       implementation        quality loop

Skills are loaded on-demand from the manifest in the bootstrap skill. The agent reads the corresponding SKILL.md only when triggered by task classification.

What Users Customize

File	What to Edit	How Often
GATES.md	Add project-specific quality rules in Custom Gates section	Once at project setup
HOOKS.md	Add/remove lifecycle actions (test commands, linters)	Once at project setup
PROJECT.md	Update when tech stack or architecture changes	Rarely
MAP.md	Auto-maintained; manual edits when adding major files	Per feature
SESSION.md	Auto-maintained by the agent between sessions	Never (agent-managed)

Architecture Reference

See docs/ARCHITECTURE.md for the complete reference covering all skills, gates, hooks, platform parity, and lifecycle flows.

License

MIT