Session 197 Handoff — Make Vitto Actually Generate Modules

Critical Context

Session 196 built the infrastructure for Vitto's memory + job mastery system. The schemas, services, APIs, frontend lib, chat plugin, prompt templates, and pipeline wiring are ALL committed and building clean. But the system doesn't work end-to-end yet. When a user asks Vitto to "create a module to manage a sports team club" in the web panel chat, the agent loop stalls after iteration 1 — it writes text but never calls start_module_generation.

What's Built (S196 — all committed, all building)

Backend (backend-vitto-api)

• vitto-users database (second Mongoose connection on same cluster)
• UserDossier schema + service (per-user structured knowledge)
• JobPlaybook schema + service (composable skill trees, 5-tier mastery, self-optimization)
• UsersController with auth guards (@Roles, @CurrentUser, /me endpoints)
• Generation pipeline wired: mastery strategy + context injected into ALL 5 prompt templates
• MindService → dossier pipeline (auto-populates from every execution)
• Self-optimization loop (cheap LLM rewrites strategy after 3+ failures)
• Token budget enforcement (800 chars brief, 2000 chars prompt)
• 39 S196 tests + 21 S195 tests passing

Frontend

• @libs-ai/vitto-intelligence NX lib (6 components, service, types)
• 7 routes in VittoUnifiedChildRoutes (/vitto/mastery, /vitto/dossier, /vitto/instructions, etc.)
• Chat mastery plugin with slash commands (/mastery, /teach, /dossier, /new-job)

What's BROKEN (Must Fix in S197)

Problem 1: Agent Loop Stalls on Module Generation Requests

Symptoms: User sends "Create a module to manage a sports team club" → SSE shows agent.iteration with iteration 1, agent.text with "Starting on the soccer club management modu..." → Then ONLY heartbeat events, no tool calls, no completion.

Root cause: The agent loop in agent-loop.service.ts is not progressing past iteration 1. The LLM responds with text but doesn't call start_module_generation. This could be:

1. The tool definitions aren't being sent correctly to the Anthropic API
2. The system prompt is too long (context overflow) causing the model to skip tool use
3. The agent loop's tool-call parsing fails silently
4. The LLM model being used doesn't support tool use (unlikely but check)

Files to investigate:

• APIs/backend-vitto-api/src/app/engine/agent-loop.service.ts — The main agentic loop
• APIs/backend-vitto-api/src/app/tools/tool-registry.service.ts — Tool definitions (line 1302: start_module_generation)
• APIs/backend-vitto-api/src/app/engine/vitto-engine.service.ts — Orchestrates the agent
• APIs/backend-vitto-api/src/app/engine/context-assembly.service.ts — Builds the system prompt (check if it's >200K tokens)

How to debug:

1. Add logging in agent-loop.service.ts at the point where it sends tools to the LLM
2. Log the exact Anthropic API response to see if tool_use blocks are present
3. Check if the system prompt exceeds the model's context window
4. Check the maxIterations setting (currently 40 — should be fine)

Problem 2: No Visual Pipeline Editor

The orchestration schema exists (PlaybookOrchestration with steps, dependencies, parallel/sequential modes) but there's no UI to:

• Visualize the pipeline steps and their dependencies
• Monitor live generation progress (which phase is running, per-skill status)
• Drag-to-reorder steps, add/remove skills, configure timeouts
• See mastery scores per skill in real-time during generation

Problem 3: Frontend Components Are Stubs

The 6 components in @libs-ai/vitto-intelligence render but:

• PlaybookCreator's "Let Vitto Help" button doesn't call the LLM
• No animations, transitions, or polish
• Executive instructions component points to /engine/executive/instructions (existing endpoints in vitto.controller.ts) but may need data shape adjustments
• UserDossierView has no real-time updates (doesn't subscribe to SSE events)

Key Files Map

Backend — Generation Pipeline

APIs/backend-vitto-api/src/app/
├── engine/
│   ├── agent-loop.service.ts          ← INVESTIGATE: Why does it stall?
│   ├── vitto-engine.service.ts        ← Orchestrates agent loop
│   ├── context-assembly.service.ts    ← System prompt (S196: dossier + mastery injected)
│   └── autonomy.service.ts            ← OBSERVE/SUGGEST/DIRECT/AUTONOMOUS levels
├── module-generation/
│   ├── phases/
│   │   ├── module-gen-phase.executor.ts  ← S196: mastery outcome recording + dossier updates
│   │   ├── enhance.phase.ts
│   │   ├── analyze.phase.ts           ← S196: playbookStrategy + masteryContext in prompt
│   │   ├── decompose.phase.ts         ← S196: same
│   │   ├── plan.phase.ts              ← S196: same (added contextHints param)
│   │   └── execute.phase.ts           ← S196: same
│   ├── context/
│   │   └── generation-context.service.ts  ← S196: fetches mastery + strategy
│   └── module-generation.module.ts    ← S196: imports UsersModule
├── tools/
│   └── tool-registry.service.ts       ← Line 1302: start_module_generation definition
├── users/                             ← NEW in S196
│   ├── schemas/
│   │   ├── user-dossier.schema.ts
│   │   └── job-playbook.schema.ts
│   ├── user-dossier.service.ts
│   ├── job-mastery.service.ts
│   ├── users.controller.ts
│   └── users.module.ts
├── mind/
│   ├── mind.service.ts                ← S196: dossierService injected, auto-populates
│   └── mind.module.ts                 ← S196: imports UsersModule
└── prompts/module-gen/
    ├── system-analyze.prompt.md       ← S196: {{playbookStrategy}} + {{masteryContext}}
    ├── system-decompose.prompt.md     ← S196: same
    ├── system-plan.prompt.md          ← S196: same
    ├── implement-visual.prompt.md     ← S196: same
    └── implement.prompt.md            ← S196: same

Frontend — Intelligence UI

libs/libs-ai/vitto-intelligence/src/lib/
├── components/
│   ├── job-mastery-dashboard/         ← Grid of all playbooks
│   ├── job-mastery-detail/            ← Single playbook deep dive
│   ├── playbook-editor/               ← Edit playbook (executive only)
│   ├── playbook-creator/              ← Create new job type (needs LLM wiring)
│   ├── user-dossier-view/             ← Tabbed dossier display
│   └── executive-instructions/        ← Directive management
├── services/
│   └── vitto-intelligence-api.service.ts  ← HTTP client (/users/* endpoints)
└── types/
    └── intelligence.types.ts

Chat Plugin

libs/libs-ai/vitto-chat/src/lib/plugins/
├── mastery.plugin.ts                  ← /mastery, /teach, /dossier, /new-job
├── plugin-presets.ts                  ← S196: mastery plugin in standard set
└── index.ts                           ← S196: exports createMasteryPlugin

Schemas Reference

UserDossier (collection: 'dossiers' in vitto-users)

userId (unique), identity, personality, expertise, workPatterns,
spaces (per-space map), relationships, timeline (cap 50),
jobMastery (per-job-type mastery overlay), brief, briefGeneratedAt,
lastInteraction, expiresAt (GDPR TTL)

JobPlaybook (collection: 'job-playbooks' in vitto-users)

jobType (unique), displayName, category, description, brief,
skills[] (composable, with embeddings), strategyVersions[] (self-optimizing),
graduationCriteria (5-tier: intern→principal), globalStats,
orchestration (steps[], maxConcurrency, pipelineTimeoutMs, failFast),
phases, origin (seeded|emergent), status, version

Seeded Playbook: code-platform-generation

7 skills: analyze-space-profile, select-template, plan-architecture,
          generate-backend, generate-frontend, verify-build, validate-output
4 orchestration steps: analyze → plan → generate (parallel) → verify (parallel)
Strategy v1: "Template-first approach..."

REST API Endpoints

GET    /users/dossier/me              ← Own dossier (any user)
GET    /users/dossier/:userId         ← Other user (executive/admin/developer)
POST   /users/dossier/me/facts        ← Learn fact (own)
POST   /users/dossier/me/corrections  ← Record correction (own)
POST   /users/dossier/me/expertise    ← Update expertise (own)
POST   /users/dossier/me/events       ← Record event (own)
POST   /users/dossier/me/brief/rebuild ← Rebuild brief (own)
DELETE /users/dossier/:userId         ← Delete (executive/admin)
GET    /users/playbooks               ← List all (any user)
GET    /users/playbooks/:jobType      ← Get one (any user)
POST   /users/playbooks               ← Create (executive/admin)
PUT    /users/playbooks/:jobType      ← Update (executive/admin)
POST   /users/mastery/:userId/:jobType/outcome ← Record outcome (system/admin)
GET    /users/mastery/:userId/:jobType ← Get mastery (own or executive)

Build Commands

npx nx build backend-vitto-api --skip-nx-cache   # Backend
npx nx build gograb-ai --skip-nx-cache            # Frontend (includes vitto-intelligence)
npx nx test backend-vitto-api --testFile="session-196"  # 39 tests
npx nx test backend-vitto-api --testFile="session-195"  # 21 tests (regression)
npx nx lint vitto-intelligence                    # Frontend lint

Priority Order for S197

1. Fix agent loop stalling — This unblocks EVERYTHING. Without it, nothing works.
2. Pipeline visualization component — Real-time generation monitoring
3. Polish frontend components — Make them production-ready
4. Wire "Let Vitto Help" in PlaybookCreator — LLM-assisted form filling
5. Live SSE events in mastery dashboard — Real-time skill score updates during generation