Skip to content

5-Minute Quickstart

Welcome to Matryoshka-Harness! In less than 5 minutes, you will fence your codebase against AI prompt bloat, audit repository maturity, compile an ultra-lean AGENTS.md boundary, catch unsafe AST code antipatterns before commit, and configure Model Context Protocol (MCP) tooling for your AI agent workflow.

📋 Prerequisites

Before starting, make sure you have either:

  • Installed Matryoshka following the Installation Guide (baba, bbyg, or matryoshka), or
  • Have bunx or npx ready to run zero-install commands on demand.

Navigate to the root directory of your project: 

cd /path/to/your/project

🔍 Step 1: Detect Repository Stack & Archetype (baba detect)

The first layer in Matryoshka is automatic stack discovery. Run baba detect to inspect your manifests and classify your repository layout:

baba detect

What Happens Behind the Scenes:

  • Identifies primary programming languages (TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP).
  • Detects application frameworks (Next.js, FastAPI, Django, Gin, Actix, Rails, Laravel).
  • Recognizes testing harnesses (Bun test, Vitest, Jest, Pytest, Go test, Cargo test).
  • Discovers architectural seams (routes, models, controllers, services, templates) and categorizes your project into a canonical archetype:
  • api_backend
  • opinionated_monolith
  • reactive_frontend
  • systems_microservice
  • fullstack_hybrid

For automated scripts or agent pipelines, emit structured JSON: 

baba detect --json

📊 Step 2: Audit Maturity & Export Compliance Badge (baba scan)

Next, assess your repository hygiene against the canonical paladini/harness-score oracle across 5 governance axes: Context, Skills, Guardrails, Sensors, and Hygiene (105 points maximum, ranking from Level 0 to Level 4).

baba scan

Exporting an Official SVG Badge

Generate a dynamic, accessible SVG compliance badge to showcase your repository maturity in your README.md:

# Generate badge in your repository:
baba scan --badge ./badges/harness.svg

# Inspect structured JSON audit:
baba scan --json

The badge color automatically calibrates based on maturity level, from Level 0 (Red #cf222e) to Level 4 (Green #2ea44f).

🛡️ Step 3: Compile Adaptive AGENTS.md & Modular Skills (baba agents generate)

Monolithic 500-line prompt files waste expensive context tokens and dilute model attention. Matryoshka solves this with adaptive context-fencing: an ultra-lean root AGENTS.md strictly under 200 tokens, combined with modular on-demand skills stored in .agents/skills/.

Previewing the Generation (Dry-Run)

Inspect planned changes and token savings without writing anything to disk: 

baba agents generate --dry-run

Generating Production Directives

Compile the root AGENTS.md and active skills based on your project's archetype: 

baba agents generate

If an AGENTS.md file already exists, Matryoshka prevents accidental data loss: 

# Force regeneration with automatic AGENTS.md.bak backup:
baba agents generate --force

Generated File Hierarchy

.
├── AGENTS.md                  # Root context fence (< 200 tokens, Token Guard hard limit < 250)
└── .agents/
    └── skills/                # Loaded only on demand via YAML frontmatter indexing
        ├── backend.md         # Framework-specific database queries & routing guidelines
        ├── frontend.md        # CLS prevention, image optimization & accessibility
        ├── database.md        # Safe indexing, migration & ORM anti-N+1 rules
        ├── security.md        # OWASP Top 10, sanitization & zero credential leakage
        └── testing.md         # The Seam Contract (Red-to-Green TDD & mock boundaries)

Auditing Token Budgets

Verify that your root AGENTS.md complies with the 250 token ceiling: 

baba agents check --json

🔬 Step 4: Polyglot AST Antipattern Verification (baba wrap)

Before committing or pushing code generated by AI coding assistants, execute Matryoshka's polyglot AST engine to detect dangerous code patterns in under 200ms:

baba wrap

Antipattern Rules Enforced:

  1. raw-sql (CWE-89): Flags dynamic SQL string interpolations, template literals, and unparameterized query calls.
  2. assertionless-test: Detects tests that execute functions without behavioral assertions (expect, assert, t.Fatal), preventing false-green test hazards.
  3. hardcoded-credential: Detects high-entropy plaintext API tokens, secret keys, and private credentials.

Automated Remediation Report (DIAGNOSTIC.md)

baba wrap writes an actionable, FinOps-budgeted remediation plan to DIAGNOSTIC.md (capped under 1,500 tokens).

Enforcing CI/CD Quality Gates

Integrate baba wrap as a strict blocking gate in your GitHub Actions pipeline: 

baba wrap --strict --threshold 80
If the composite health score falls below 80 or any critical AST violation exists, the command exits with code 1.

🔌 Step 5: Wire MCP for AI Coding Assistants (baba mcp wire & serve)

Connect your development environment to Matryoshka's native Model Context Protocol (MCP) suite.

Auto-Wiring MCP Servers

Automatically inject codebase-memory-mcp into your agent IDE configuration files (.cursor/mcp.json, .claude/mcp.json, .gemini/settings.json):

# Auto-wire all detected targets:
baba mcp wire

# Or wire specific IDE targets:
baba mcp wire --targets cursor,claude

Launching Native stdio MCP Server

Launch the native JSON-RPC 2.0 stdio MCP server for direct integration with Cursor, Zed, Claude Code, or Aider:

baba mcp serve

The native MCP server exposes 4 core tools:

  • detect_stack — Polyglot language and framework inspection.
  • scan_harness — Maturity assessment (L0 to L4) and gap scoring.
  • generate_agents — Adaptive AGENTS.md compilation and modular skill provisioning.
  • wrap_context — In-memory AST antipattern verification and remediation action plan.

Congratulations! Your repository is now fully fenced with Matryoshka-Harness.