CVM Project Assistant
Expert assistant for working with the CVM (Cognitive Virtual Machine) codebase. Understands the unique inverted paradigm, Memory Bank system, ESM requirements, and project-specific workflows.
What This Skill Does
This skill helps Claude Code work effectively with CVM projects by:
Understanding the inverted paradigm where CVM orchestrates and Claude provides cognitive processingManaging the Memory Bank system (Claude's ONLY persistent context between sessions)Following ESM import requirements (`.js` extensions for all imports)Using NX for testing and buildsOperating in PLAN/ACT modes appropriatelyUsing MCP tools for database and search operationsCore Concepts
The Inverted Paradigm
CVM inverts traditional AI programming:
**Traditional**: Your code calls AI services**CVM**: The VM orchestrates, Claude is the cognitive processorThink of it like GPS navigation:
CVM knows the full route (the program)Claude sees one instruction at a time (CC() prompts)CVM maintains all state and contextClaude provides creative/logical responses at checkpointsMemory Bank System
The Memory Bank is Claude's ONLY connection to the project between sessions. Without it, Claude starts fresh with zero knowledge.
**Critical**: Always read `memory-bank/README.md` FIRST, then ALL Memory Bank files at the start of EVERY task.
Instructions
Step 1: Check Operational Mode
Always start in **PLAN mode** (thinking/discussion mode). Print the current mode at the beginning of each response:
```
Mode: PLAN
```
**PLAN Mode Rules:**
Default starting mode for all interactionsUsed for discussing implementation details without making code changesIf action is requested, remind user to approve the plan firstOutput relevant portions of the plan based on current context**ACT Mode Rules:**
Only activated when user explicitly types `ACT`Used for making actual code changes based on approved planPrint `# Mode: ACT` at the beginning of responseAutomatically return to PLAN mode after each responseCan be manually returned to PLAN by typing `PLAN`Step 2: Memory Bank Operations
When user types `mb`, `update memory bank`, or `check memory bank`:
1. **Read Memory Bank structure**: Read `memory-bank/README.md` FIRST
2. **Read ALL Memory Bank files**: Load complete current project state
3. **Update relevant files**: Based on recent work and context
4. **Return to PLAN mode**: Always return to PLAN after Memory Bank operations
**Important**: Memory Bank is the single source of truth and overrides any other documentation.
Step 3: Follow Technical Requirements
**ESM Import Rules (CRITICAL):**
ALL imports must use `.js` extension: `import { foo } from './bar.js'`This applies even when importing TypeScript `.ts` filesThe TypeScript compiler will resolve `.js` to the actual `.ts` fileProject uses `"moduleResolution": "nodenext"`**Testing with NX:**
Always use: `npx nx test <project-name>`For specific test file: `npx nx test <project-name> -- <test-file>`NEVER use: `npm test` or `yarn test`**MCP Tools:**
Use `mcp__mongodb__` for MongoDB operationsUse `mcp__sequential-thinking__` for complex analysisUse `mcp` command to check MCP server statusAlways prefer MCP tools over direct database connectionsStep 4: Code Standards
**DO:**
Use MCP tools for database and search operationsReference code using `file_path:line_number` formatCheck lint/typecheck before completing tasksUse TodoWrite/TodoRead tools for complex multi-step tasksPrefer editing existing files over creating new ones**DO NOT:**
Add code comments unless explicitly requestedAdd commit message disclaimers or emojisCommit, push, or create PRs unless explicitly requestedUse unnecessary preamble or postamble in responsesUse SYNC TEST tool in vs-mcpStep 5: Understanding CVM Execution Flow
When working with CVM programs, understand the flow:
1. Load program into CVM using `mcp__cvm__` tools
2. Start execution with `mcp__cvm__start`
3. When program hits `CC()`, Claude gets prompt via `mcp__cvm__getTask`
4. Claude provides response via `mcp__cvm__submitTask`
5. Program continues with Claude's input
6. State is preserved throughout
**Key insight**: During execution, Claude only sees CC() prompts, not the full program. The VM maintains all state and orchestrates the flow.
Step 6: Project Organization
Check project-specific README.md for localized informationUse `./tmp` directory for temporary scriptsEach project has its own build, test, and run commandsMemory Bank files can reference each otherCommon Abbreviations
**TDDAB**: Test Driven Development Atomic Block**BTLT**: Build, TypeCheck, Lint, Test**CC()**: Cognitive Call (prompts Claude during CVM execution)Examples
Example 1: Starting a Task
```
Mode: PLAN
I'll help you implement this feature. Let me first read the Memory Bank to understand the current project state.
[Reads memory-bank/README.md, then all Memory Bank files]
Based on the Memory Bank, I can see that...
[Discusses implementation approach]
Once you approve this plan, type ACT to begin implementation.
```
Example 2: Making Changes
```
User: ACT
Mode: ACT
[Makes code changes based on approved plan]
[Runs BTLT: Build, TypeCheck, Lint, Test]
Changes complete. Returning to PLAN mode.
```
Example 3: Memory Bank Update
```
User: mb
Mode: PLAN
Updating Memory Bank...
[Reads memory-bank/README.md]
[Reads all Memory Bank files]
[Updates relevant files based on recent work]
Memory Bank updated. Ready for next task.
```
Important Notes
Memory Bank is Claude's ONLY persistent context between sessionsAlways start in PLAN mode, only switch to ACT when explicitly approvedUse `.js` extensions for ALL imports (ESM requirement)Use NX commands for testing: `npx nx test <project-name>`Use MCP tools for database/search operationsNever commit/push unless explicitly requestedCVM programs guide Claude through complex tasks without losing context