AI-Assisted Development

BioMapper features a comprehensive AI-native developer experience through the BioMapper Framework Triad - three specialized isolation frameworks that automatically activate based on natural language descriptions of development tasks. This system is implemented in the src/core/safety/ module and provides seamless, transparent framework selection and execution.

This section documents how these frameworks work, how they’re triggered, and how to use them effectively with AI agents like Claude Code.

Note

The frameworks can be activated in two ways:

Direct activation - Use the framework name (“surgical”, “circuitous”, “interstitial”) anywhere in your message
Automatic detection - Describe the problem naturally and the UnifiedBiomapperAgent will select the appropriate framework using pattern matching and confidence scoring

Both methods work equally well. The unified agent uses a confidence threshold of 40% for activation.

Framework Overview

The BioMapper Framework Triad consists of three specialized frameworks:

Framework Quick Reference
Framework	Purpose	Example Trigger
🔒 Surgical	Fix internal action logic	“The statistics are counting duplicates”
🔄 Circuitous	Repair pipeline flow	“Parameters not passing between steps”
🔗 Interstitial	Ensure compatibility	“New parameter broke existing strategies”

Key Concepts

Automatic Activation: The UnifiedBiomapperAgent detects intent from natural language using pre-compiled regex patterns and confidence scoring with keyword boosting. No explicit framework names needed.
User-Transparent Operation: The frameworks operate invisibly through the FrameworkRouter - you describe problems naturally and the appropriate framework activates automatically with confidence threshold of 40%.
100% Backward Compatibility: The Interstitial Framework guarantees that all interface changes maintain complete backward compatibility using automatic compatibility layers and alias mapping.
Generic Application: All frameworks work with ANY action type through the ACTION_REGISTRY - they’re not limited to specific biological entities or operations.

How It Works

The UnifiedBiomapperAgent uses a sophisticated routing pipeline:

You describe a problem in natural language
Pattern matching - Pre-compiled regex patterns check for framework-specific triggers
Confidence scoring - Calculates match confidence with base score + keyword bonuses
Ambiguity resolution - Uses priority order: Surgical → Interstitial → Circuitous
Framework activates automatically if confidence ≥ 40%
Target extraction - Identifies specific actions/strategies from the message
Fix is applied with appropriate isolation guarantees

Example Workflow

User: "The protein mapping shows 3675 proteins but there are only 1172 unique ones"

Agent: [FrameworkRouter detects pattern match → Confidence: 85% → Activates Surgical Framework]
       🔒 Surgical mode activated
       🎯 Target: GENERATE_MAPPING_VISUALIZATIONS (detected from ACTION_REGISTRY)
       ✅ Fixed: Now counting unique entities via df['uniprot'].nunique()

User: "Make sure this doesn't break the pipeline"

Agent: [Pattern matches pipeline concern → Confidence: 75% → Activates Circuitous Framework]
       🔄 Circuitous mode activated
       📋 Strategy: auto-detected from context
       ✅ Pipeline integrity validated - all interfaces preserved

Contents

Quick Links

BioMapper Framework Triad - Complete framework documentation
Framework Triggering Mechanics - How automatic detection works
Slash Commands Reference - Manual framework activation
Real-World Usage Examples - Real-world usage scenarios

Integration with Claude Code

When using Claude Code with BiOMapper:

Describe problems naturally - Don’t worry about framework names
Trust automatic detection - The agent will choose the right framework
Provide context - Include action/strategy names when known
Review the approach - The agent will explain which framework is active

Best Practices

Be specific about the problem you’re experiencing
Include examples of incorrect behavior when possible
Mention action/strategy names to help with targeting
Don’t force frameworks - let automatic detection work
Report misdetections to improve pattern matching