Developer CLI & Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Developer CLI & Workflow in the Memory Context Browser (MCB) project is built around a "monopoly script" architecture designed to enforce consistency, quality gates, and project rules. The primary entry point for all development activities is a set of canonical make verbs backed by the centralized scripts/lib/mcb.sh utility. This approach ensures that every contributor, whether human or AI agent, adheres to the project's strict engineering standards, including Clean Architecture enforcement and zero-tolerance for unsafe code or unverified failures.
The workflow prioritizes surgical edits and root-cause fixes, validated through a multi-layered testing and linting pipeline. Developers interact with the system primarily through the mcb CLI facade, which provides subcommands for server management, semantic search, indexing, and architecture validation. The environment is highly governed, utilizing pre-commit hooks and a "banned-pattern" guard to prevent common pitfalls such as the use of unwrap() or todo! in production code paths.
Sources: README.md:92-101, AGENTS.md:144-150, CONVENTIONS.md:11-20
CLI Command Structure
The MCB project uses a tiered CLI structure. The top-level mcb binary serves as a facade for various specialized operations, delegating to internal crates such as mcb-server and mcb-validate. The developer workflow is primarily driven by the Makefile, which maps user-friendly verbs to complex shell logic.
Canonical Make Verbs
Development lifecycle commands follow the pattern: make <verb> [WHAT=phase] [SCOPE=...] [APPLY=Y]. Direct use of cargo or git for mutating operations is generally discouraged in favor of these verbs to ensure all automated guards are executed.
| Verb | Description | Key Phases (WHAT) |
|---|---|---|
build | Compiles the project | RELEASE=0|1 |
check | Runs quality gates | fmt, lint, validate, audit, qlty, all |
test | Executes test suites | unit, doc, golden, integration, e2e, all |
fix | Automated mutation | fmt, lint, docs, all |
docs | Documentation management | build, serve, lint, validate, adr |
release | Packaging and install | package, version, install |
Sources: AGENTS.md:152-170, README.md:123-130
The Monopoly Script (mcb.sh)
The scripts/lib/mcb.sh script acts as the Single Source of Truth (SSOT) for executable logic. It handles exit codes, the APPLY=Y safety gate for destructive operations, and the "agent bash-guard" which intercepts potentially non-compliant shell commands.
The diagram shows the command execution flow where mcb.sh acts as a mandatory middleware for validation before executing underlying toolchain commands.
Sources: AGENTS.md:144-150, AGENTS.md:188-200
Quality Gates & Validation
The workflow enforces "Clean Architecture" boundaries and code quality through a combination of Rust's type system and custom validation tooling. All contributions must pass four primary gates: lint, test, validate, and guard.
Architecture Enforcement
Architecture rules are enforced by the mcb-validate crate. It ensures that dependencies flow strictly inward (e.g., mcb-domain must have zero internal dependencies). Violations are blocked at both the developer level and the pre-commit stage.
The Guard Protocol
The make guard command scans the codebase for "banned patterns." This includes:
- Production use of
unwrap(),expect(),panic!, ortodo!. - Unjustified use of
#[allow(...)]ornoqadirectives. - Strict-total compliance: A bypass that hides a symptom is treated as a defect even if the gate turns green.
Sources: AGENTS.md:31-40, AGENTS.md:200-204, CONVENTIONS.md:11-18
Multi-Agent Coordination Workflow
The repository is designed to support multiple AI agents working in the same tree simultaneously. This requires a "Fix-Forward-Only" philosophy where reverting state is forbidden without explicit user confirmation.
Coordination Protocol
Agents coordinate through a committed task board located at .agents/coordination/tasks.md. The workflow involves:
- Claiming: Adding an ownership and lease entry before editing.
- Heartbeating: Updating the lease to show active progress.
- Committing: Making small, frequent commits so subsequent agents can rebuild state from
git log. - Evidence: Every "Done" state must be accompanied by objective evidence (command + exit code + output).
This sequence illustrates how agents use a shared file and git history to maintain context without overwriting each other's work.
Sources: AGENTS.md:52-60, AGENTS.md:111-118
Project Implementation Rules
When implementing features or fixes, developers must follow a strict modularization and error handling strategy.
- MVI 200: Source files should remain under ~200 lines; they must be split into submodules if they grow beyond this limit.
- Error Handling: Developers must use specific constructors like
Error::vcs("msg")frommcb-domain. RawResultor generic errors are discouraged to maintain domain-specific context. - Surgical Edits: Refactors or renames unrelated to the current task are forbidden. Developers are instructed to stay in scope and mention unrelated issues in a single sentence rather than fixing them.
Sources: CONVENTIONS.md:11-20, AGENTS.md:67-71
Conclusion
The MCB Developer CLI & Workflow is a highly structured environment that leverages the "monopoly script" pattern to ensure technical excellence. By routing all commands through make and mcb.sh, the project automates the enforcement of Clean Architecture and strict coding standards. This workflow effectively bridges the gap between human developers and AI agents, providing a predictable, safe, and high-quality development experience.
Sources: AGENTS.md:144-150, README.md:132-140