Guide the creation of a high-quality mental model for a codebase. Use when starting a new mental model, when the model feels incomplete or unclear, or when onboarding to understand a system's architecture. Produces domains, capabilities, aspects, and architectural decisions.
Create a comprehensive mental model that captures how a system actually works - not just what files exist, but the conceptual boundaries, responsibilities, decisions, and connections that shape it.
A good domain model answers:
--operates-on connections!)--applies-to connections!)CRITICAL: Every capability MUST have --operates-on linking it to domains. Every aspect MUST have --applies-to. Orphan entities indicate incomplete modeling.
Before modeling, understand the codebase structure. Launch parallel agents to explore different aspects simultaneously:
Agent 1: "Read README.md, package.json, and entry points. What problem does this solve? Who are the users?"
Agent 2: "List all top-level directories. What's in each? (src/, lib/, apps/, packages/, etc.)"
Agent 3: "Find configuration files (*.config.*, .env*, etc.). What can be configured?"
Agent 4: "Search for 'export class' or 'export function' in key directories. What are the main abstractions?"
Agent 5: "Look for test directories. What's being tested? This reveals important functionality."
Agent 6: "Search for API routes, CLI commands, or event handlers. What are the entry points?"
Agent 7: "Look for database models, schemas, or types. What data does this system manage?"
Agent 8: "Search for external integrations (HTTP clients, SDKs, third-party services)."
Output: A map of the codebase with preliminary domain candidates.
For each potential domain area discovered in Phase 1, launch a dedicated agent:
For EACH major directory or subsystem, launch an agent with this prompt:
"Thoroughly explore [DIRECTORY] in [REPO_PATH]. Answer:
1. What domain concepts exist here? (nouns - things with identity)
2. What capabilities does it provide? (verbs - actions that can be performed)
3. What does this area depend on? (imports, calls to other modules)
4. What depends on this area? (who imports/uses this)
5. What architectural decisions are visible? (patterns, trade-offs)
6. List key files and their purposes.
Be comprehensive - read the actual code, don't just list files."
Example for a large codebase with 15 directories:
Launch 15 agents in parallel, one for each:
- src/auth/
- src/users/
- src/payments/
- src/notifications/
- src/api/
- src/database/
- apps/web/
- apps/mobile/
- packages/shared/
- packages/ui/
- src/infrastructure/
- src/integrations/
- src/jobs/
- scripts/
- etc.
Each agent should return:
Based on agent findings, create entities using the mental CLI:
mental add domain <Name> \
--desc "What it represents, its lifecycle, key attributes" \
--files "path/to/key/files.ts,another/file.ts"
Good domains:
Anti-patterns to avoid:
mental add capability <Name> \
--desc "What it does, when it's triggered" \
--files "path/to/implementation.ts" \
--operates-on "Domain1,Domain2,Domain3"
CRITICAL: Always include --operates-on to connect capabilities to domains!
After adding, verify with:
mental update capability <Name> --operates-on "Domain1,Domain2"
Good capabilities:
mental add aspect <Name> \
--desc "What cross-cutting concern it addresses" \
--files "path/to/implementation.ts" \
--applies-to "Capability1,Domain2,Capability3"
CRITICAL: Always include --applies-to to show what the aspect affects!
Good aspects:
mental add decision "<What was decided>" \
--why "Rationale, constraints, trade-offs"
Capture at least 5-10 significant architectural decisions.
After initial modeling, launch verification agents to find gaps:
Agent 1: "List all domains in the mental model. For each, what capabilities operate on it?
Flag any domains with zero capabilities - these are orphans that need capabilities added."
Agent 2: "List all capabilities. Do they all have operates-on connections?
Flag any without connections and suggest which domains they should connect to."
Agent 3: "List all aspects. Do they all have applies-to connections?
Flag any without connections and suggest what they should apply to."
Agent 4: "Compare the directory structure to the mental model.
Are there major directories not covered by any domain? List gaps."
Agent 5: "Review the decisions captured. Are there obvious architectural patterns
(monorepo, microservices, event-driven, etc.) not documented? What's missing?"
Agent 6: "For each domain, are there CRUD-like capabilities? (Create, Read, Update, Delete, List)
Many domains should have management capabilities - flag domains that seem incomplete."
Before considering the model complete:
--operates-on connections--applies-to connectionsIf gaps are found, launch targeted agents to fill them:
"Domain X has no capabilities. Explore the files for X and find what actions/operations
can be performed on it. Look for: create, update, delete, list, validate, transform, etc."
"Capability Y has no operates-on. Read the implementation and determine which domains
it actually works with. What data does it read? What does it modify?"
"Directory Z is not covered by the model. Explore it thoroughly and determine if it
represents a new domain, capabilities for existing domains, or cross-cutting aspects."
Use mental update to fix connections:
mental update capability <Name> --operates-on "Domain1,Domain2"
mental update aspect <Name> --applies-to "Capability1,Domain2"
| Codebase Size | Domains | Capabilities | Aspects | Decisions | Total Agents | |---------------|---------|--------------|---------|-----------|--------------| | Small (<50k LOC) | 4-8 | 10-20 | 3-5 | 3-5 | 10-15 | | Medium (50-200k) | 8-15 | 20-40 | 5-10 | 5-10 | 20-30 | | Large (200k+) | 12-20 | 30-60 | 8-15 | 10-20 | 30-50 |
Don't be afraid to launch many agents - parallel exploration is much faster than sequential.
Phase 1 (8 agents in parallel): Quick survey → identify ~20 potential areas Phase 2 (20 agents in parallel): Deep dive each area → raw findings Phase 3: Synthesize into 15 domains, 35 capabilities, 8 aspects, 12 decisions Phase 4 (6 agents in parallel): Verify completeness → find 8 gaps Phase 5 (8 agents in parallel): Fill gaps → add missing connections
Total: ~42 agent launches, model complete in one session
--operates-on - Capabilities without domain connections are useless--applies-to - Aspects without targets don't show their impact# Add entities
mental add domain <Name> --desc "..." --files "..."
mental add capability <Name> --desc "..." --files "..." --operates-on "Dom1,Dom2"
mental add aspect <Name> --desc "..." --files "..." --applies-to "Cap1,Dom2"
mental add decision "<What>" --why "..."
# Update connections (IMPORTANT!)
mental update capability <Name> --operates-on "Dom1,Dom2,Dom3"
mental update aspect <Name> --applies-to "Cap1,Cap2,Dom1"
mental update domain <Name> --desc "new description"
# View model
mental show # Text output
mental view # Interactive visualization in browser
# Delete if needed
mental delete domain <Name>
mental delete capability <Name>
mental delete aspect <Name>
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer