Virtual Josef -- System Architecture

AI-native executive operating system for Josef Buryan, CMO at Groupon. Built on Claude Code CLI.
Document generated: 26-03-2026 | Root: /Users/jburyan/Documents/Claude

1 System Overview

The system is a multi-project Claude Code workspace that implements "Virtual Josef" -- a command-driven, AI-native executive operating system. It is not a chatbot. Every user message is treated as a command; output is structured delivery using predefined templates, skills, and data pipelines.

Core Identity

User: Josef Buryan, CMO, Groupon (Prague, CZ)
Role: AI Chief of Staff -- blunt operator, CMO-level growth thinker, execution partner
Mode: Command-driven. No conversation, no questions, no suggestions.
Personality: Direct, precise, structured, zero-filler. "Senior McKinsey partner who bills by the minute."
Primary tool: Claude Code CLI (Opus 4.6)
Blueprint: VIRTUAL_JOSEF_BLUEPRINT.md (79K -- full product spec and roadmap)

Command Processing Pipeline (15 steps)

Every command follows this pipeline in order:

Receive command as-is
Classify command type from signal words (12 types)
Check depth modifiers (brief / standard / deep dive)
Extract entities (metrics, dates, people, projects)
Check blocking inputs -- Missing Inputs protocol if unreliable
Resolve references (implicit "that", "this", "same for")
Read memory files (user profile, strategic context, etc.)
Check feedback log (corrections + preferences for command type)
Determine tools (MCP, web search, file reads)
Execute retrieval (parallel where possible)
Generate output using template at determined depth
Validate truth (replace unverifiable claims)
Format (tables, dates DD-MM-YYYY, USD, percentages 1 decimal)
Strip prohibited patterns (questions, offers, emojis, filler)
Deliver and stop

2 Directory Structure

3 Guardrails (CLAUDE.md)

The root CLAUDE.md defines 12 system safety guardrails that apply across all subprojects.

1. Filesystem Safety

No rm, unlink, rmdir ever. Move to _trash/ instead.

2. Secrets Protection

Never print/log API keys. Use ${ENV_VAR} references. Never hardcode.

3. Git Safety

No force push to main. No hard reset without confirmation. No secret commits.

4. Reference Immutability

All files in shared/config/ are read-only during automated runs.

5. Output Containment

Generated artifacts go to results/, reports/, outputs/ only. Never to source dirs.

6. Cost Guardrails

Warn at $0.25/run, abort at $0.50/run. No bypass without confirmation.

7. Autonomous Loop Rules

Every loop needs: task description, iteration limit, completion condition.

8. Truth and Data Integrity

Never fabricate. Cite sources. Label assumptions. Use ranges for projections.

9. Formatting Standards

DD-MM-YYYY, USD, 1 decimal %, K/M/B notation, tables over paragraphs.

10. External Systems Read-Only

No modification without explicit approval. No sending comms.

11. Behavioral Defaults

No emojis, no fluff, structure-first, stop when done.

12. Workflow Orchestration

Plan mode for 3+ step tasks. Subagents liberally. Self-improvement loop. Task tracking.

4 Rules (.claude/rules/)

Four always-active rule files that override default Claude behavior. Loaded automatically for every session in this project.

immutable-rules.md

.claude/rules/immutable-rules.md

15 non-overridable rules: no fabrication, no questions, no suggestions, no affect mirroring, no emojis, no point estimates, no stale data without flagging, source citation required, no PII storage, no unauthorized external writes.

output-discipline.md

.claude/rules/output-discipline.md

Response structure order: (1) answer/recommendation, (2) supporting structure, (3) evidence, (4) assumptions, (5) missing inputs, (6) stop. Banned phrases list (13 patterns). Meta-command exception for system-building.

skill-enforcement.md

.claude/rules/skill-enforcement.md

Entry gates: pattern-match commands to skills before acting (5/15, content, morning brief, 1:1, WBR, channels, overdue, what-if, write-my-515). Exit gates: offer second-opinion after plans, run verification after changes, verify all steps before "done".

truth-and-formatting.md

.claude/rules/truth-and-formatting.md

Truth policy with 4 confidence levels (HIGH/MEDIUM/LOW/NONE). Source hierarchy (7 tiers: data pull > user-stated > verified doc > memory > older doc > inferred > general). Stale data thresholds: financial 7d, perf marketing 3d, market 30d, org 90d, strategy 90d, benchmarks 180d.

5 Virtual Josef (Company/Assistant)

The core system. A 28K CLAUDE.md file defining 13 sections of system instructions. It is a git submodule.

CLAUDE.md Sections

#	Section	Purpose
1	Identity	Role, user, mode, personality definition
2	Behavioral Rules	10 immutable rules table (no questions, no fluff, etc.)
3	Truth Policy	Confidence levels, source hierarchy, stale data, conflicts
4	Command Classification	12 command types with signal words, templates, retrieval flags + depth modifiers + multi-command handling
5	Command Processing Pipeline	15-step pipeline from receive to deliver-and-stop
6	Output Rules	Structure hierarchy, formatting standards, prohibited patterns
7	Output Templates	12 template file mappings
8	Memory Protocol	11 memory files, update triggers, conflict resolution, feedback processing
9	Integration Map	10 integrations (6 connected, 2 pending, 2 not connected) + tool usage rules
10	Data Ingestion	Input directory structure, data resolution order (5 tiers), DuckDB local SQL, format handling
11	Framework Selection	Business framework defaults by command type (ICE, Porter, AARRR, etc.)
12	Action Items	Owner/deadline/priority/deliverable rules for recommendations
13	Immutable Rules	15 rules that cannot be overridden by any instruction

6 Skills Catalog

Assistant Skills (29)

Each skill lives in Company/Assistant/skills/{name}/SKILL.md. Skills are invoked via command classification or the skill-nudge hook.

Core Operational Skills

Skill	Trigger	Purpose
morning-brief	"daily digest"	Daily morning brief: calendar, Asana tasks, 1:1 flags, conflicts
weekly-battle-rhythm	"weekly battle rhythm"	Weekly business review synthesis
review-1s	"check 5/15"	Review direct reports' 5/15 submissions, generate feedback
write-my-515	"write my 5/15"	Generate Josef's own 5/15 report for CEO
one-on-one-prep	"prep for my 1:1"	1:1 meeting prep with calendar + Asana context
overdue-task-sweeper	"overdue task sweeper"	Sweep and report overdue Asana tasks
content-factory	"content factory"	Cross-team content production (ad copy, email, social, SEO)
refresh-context	"refresh context"	Update memory files from current data sources
watchdog	"watchdog"	Monitoring and alerting skill

Channel Status Skills (11)

Skill	Channel/Area
sem	Search Engine Marketing
display	Display Advertising
seo-status	SEO Performance
seo-tech	SEO Technical
crm-status	CRM and Email Marketing
affiliates	Affiliate Channel
influencers	Influencer Marketing
brand-status	Brand Marketing
brand-social	Brand Social Media
merch-status	Merchandising
aog-status	AOG Status

Strategic / Status Skills

Skill	Purpose
pp-status	Pricing and Promotions status
pp-experiments	Pricing and Promotions experiments
coupons-status	Coupons channel status

Meta / System Skills

Skill	Purpose
what-if	Scenario modeling (budget, HC, strategy, market, pricing changes)
second-opinion	Multi-model review: Claude subagent + OpenAI Codex cross-validation
self-improve	System self-improvement analysis
system-health	System health diagnostics
swarm	Multi-agent parallel analysis (Tableau, BigQuery, Calendar)
run-analytics	Trigger Marketing Analytics pipeline
query-515	Query 5/15 intelligence database

Shared Skills (13)

Located in shared/skills/. Generic development and analysis skills, not Virtual Josef-specific.

Foundry Skills (6)

Skill	Category
code-review	Development
python-development	Development
test-driven-development	Development
debugging	Development
git-workflow	Development
cicd-pipelines	Development
prompt-engineering	AI/LLM
critical-intuition	Analysis
prioritization	Analysis
risk-management	Analysis
systems-thinking	Analysis
skill-creator	Meta
data-catalog-assistant	Data

Located in Company/Foundry/skills/. Track Groupon's AI transformation program.

Skill	Purpose
foundry-status	Program dashboard: HC, cost, agents, initiatives vs. targets
foundry-risks	Surface blockers, overdue initiatives, dependency conflicts
foundry-prep	Meeting briefing (offsite, biweekly, S-Team)
foundry-update	Draft CEO communication from all signals
foundry-team	Deep dive on a specific team
foundry-sync	Reconcile Asana project state with YAML configs

7 Output Templates

Located in Company/Assistant/templates/. Each command type maps to a template. The system reads the template before generating output and follows its structure exactly.

Template	Command Type	Format
515-feedback.html	5/15 feedback generation	HTML (19K)
content-factory.html	Content production	HTML (13K)
skill-catalog.html	Skill catalog display	HTML (25K)
decision-brief.md	Decision support	Markdown
wbr.md	Weekly Business Review	Markdown
meeting-brief.md	Meeting prep	Markdown
one-on-one-prep.md	1:1 meeting prep	Markdown
daily-digest.md	Morning brief / daily digest	Markdown
exec-comms.md	Executive communications	Markdown
experiment-spec.md	Experiment / A/B test design	Markdown
performance-analysis.md	Performance analysis	Markdown
comparison.md	Comparison / benchmark	Markdown
status-summary.md	Project status	Markdown

8 Shared Config (shared/config/)

Single source of truth. Immutable during automated runs (guardrail #4). Referenced by Assistant, Foundry, and Marketing Analytics via symlinks.

thresholds.yaml

shared/config/thresholds.yaml

Anomaly detection (z-score, 2.0 threshold, 8-week lookback), pacing alerts (5% linear), traffic light thresholds (green/yellow/red), comparison rules (WoW/YoY day alignment, 5% min delta), data freshness thresholds (3-180 days by type).

metric-definitions.yaml

shared/config/metric-definitions.yaml

12K file. All metric definitions with formulas, units, direction, targets, owners, applicable channels. Categories: revenue (GMV, revenue, take rate, orders, AOV), acquisition, engagement, efficiency.

org-structure.md

shared/config/org-structure.md

Organizational structure: CMO direct reports (current 10 + post-reorg 5), cross-functional stakeholders (CEO, CFO, COO, CTO, AI lead), meeting cadences with times/days.

integrations.yaml

shared/config/integrations.yaml

Integration state: Asana (workspace + user GIDs), Google Calendar (primary, Europe/Prague), Google Sheets (pending setup), Tableau, BigQuery, Data Catalog, Twitter, Gmail (not connected), DuckDB local, OpenAI Codex (second opinion).

content-factory.yaml

shared/config/content-factory.yaml

21K file. Brand voice definition (core identity, personality, tone spectrum: formal/standard/casual), content type specs, team mappings, variant generation rules, quality gates for Content Factory skill.

data-routes.yaml

shared/config/data-routes.yaml

Data pipeline routes: Marketing Analytics output -> Assistant input/analytics (active), Meta-Ads output -> Assistant input/meta-ads (new), Meeting Notes output -> Assistant input/meeting-notes (new).

schedule.yaml

shared/config/schedule.yaml

7 scheduled jobs: daily-digest (07:00 daily), weekly-battle-rhythm (Mon 07:00), weekly-515 (Thu 16:00), friday-sweep (Fri 07:00), meta-audit (Mon 07:30), meeting-notes (every 2h), monitor (18:00 daily). Uses launchd plist labels.

9 Scripts

Shared Scripts (shared/scripts/)

Script	Purpose	Key Commands
`asana_api.py`	Zero-dependency Asana REST API CLI. Replaced MCP Asana tools on 26-03-2026.	list-workspaces, get-task, get-subtasks, get-tasks, get-sections, get-stories, get-attachments, download-attachment, search, create-task, create-story, update-task
`intel_515_db.py`	5/15 Intelligence SQLite database -- schema + CRUD operations	init, stats, dump-people
`ingest_515.py`	5/15 data ingestion -- seeds people, backfills .md files, ingests weekly from Asana	seed, backfill, weekly YYYY-MM-DD, pull-deep YYYY-MM-DD
`analytics_515.py`	5/15 team health analytics -- submission rates, trends, reporting	compute YYYY-MM-DD, compute --all, report YYYY-MM-DD, trend <metric>
`search_515.py`	5/15 semantic search using TF-IDF + cosine similarity	build-index, search "query", who "query"
`duckdb_utils.py`	DuckDB local SQL on CSV/Parquet/JSON files	query "SQL", csv2parquet, describe "file", cache "SQL" "output.parquet"

Assistant Scripts (Company/Assistant/scripts/)

Script	Purpose
`parallel-morning-brief.py`	Parallel execution orchestrator for daily digest (scheduled via launchd)
`parallel-wbr.py`	Parallel execution orchestrator for weekly business review (scheduled via launchd)

10 Memory System

Three tiers of memory: (1) Assistant runtime memory, (2) shared memory via symlinks, (3) Claude persistent project memory.

Assistant Memory (Company/Assistant/memory/)

File	Type	Purpose	Read When
user-profile.md	Local	User identity, role, direct reports, preferences, stakeholders	Every command
feedback-log.md	Local	Corrections to past outputs, user preferences for future outputs	Every command
outcomes-log.md	Local	Recommendation outcomes and learnings	After recs, retros
skill-invocations.yaml	Local	Skill usage tracking	system-health, self-improve
strategic-context.md	Symlink	Priorities, OKRs, budget, business model, competitors	Analysis, decisions, WBR
metric-definitions.yaml	Symlink	Metric formulas, targets, thresholds	Metric/KPI commands
org-structure.md	Symlink	Reporting lines, meeting cadences	Meeting prep, status
decisions-log.md	Symlink	Past decisions and outcomes	Decisions, retros
known-issues.md	Symlink	Active issues and blockers	WBR, status, analysis
integrations.yaml	Symlink	Cached integration state	Integration commands
projects/*.md	Local	Per-project context files	Project-specific commands

Shared Memory (shared/memory/)

These are the symlink targets. Single source of truth shared across Assistant, Foundry, and other modules.

strategic-context.md -- Business model, priorities, OKRs, budget, competitive landscape
decisions-log.md -- Decision history with outcomes tracking
known-issues.md -- Active issues and blockers

Foundry Memory (Company/Foundry/memory/)

foundry-context.md -- CEO directive, non-negotiable principles, key dates
integrations.yaml -- Symlink to shared/config/integrations.yaml
metric-definitions.yaml -- Symlink to shared/config/metric-definitions.yaml
org-structure.md -- Symlink to shared/config/org-structure.md

11 Integrations and MCP Servers

Integration	Status	Protocol	Use Cases
Google Calendar	Connected	MCP: `claude_ai_Google_Calendar`	Meeting prep, scheduling context, agenda review, daily digest
Asana	Connected	Direct API: `asana_api.py`	Task tracking, 5/15 submissions, project status, overdue sweep
Tableau	Connected	MCP: `tableau`	Dashboard data, view images, datasource queries, Pulse insights
BigQuery	Connected	MCP: `bigquery`	SQL queries, dataset/table exploration
Data Catalog	Connected	MCP HTTP: `data-catalog`	Metadata search, data lineage, glossary
Notion	Connected	MCP: `@notionhq/notion-mcp-server`	Page creation, search, database queries (global config)
Gmail	Connected	MCP: `claude_ai_Gmail`	Search messages, read threads, create drafts
Twitter/X	Connected	MCP: `twitter-mcp`	Social monitoring, competitor tracking, posting
Google Sheets	Pending	WebFetch CSV export	KPI targets, budget sheets, WBR data
DuckDB (Local)	Connected	Python CLI: `duckdb_utils.py`	Local SQL on CSV/Parquet/JSON, cross-file joins, caching
OpenAI Codex	Available	CLI: `@openai/codex`	Second opinion / multi-model review (Reviewer 2)

MCP Server Configuration

Global (~/.claude.json)

notion -- @notionhq/notion-mcp-server (stdio, npx)

Project-level (.claude.json)

data-catalog -- HTTP MCP at datacatalog.groupondev.com/mcp
gdrive -- @modelcontextprotocol/server-gdrive (stdio, npx)

Claude AI Built-in (Remote MCP)

claude_ai_Google_Calendar -- Calendar read/write
claude_ai_Asana -- Asana API (mostly replaced by asana_api.py)
claude_ai_Gmail -- Gmail read + drafts
tableau -- Tableau Server (PAT auth)
bigquery -- Google BigQuery

12 Hooks and Automation

Configured in .claude/settings.local.json. Hooks fire on specific lifecycle events.

prompt-history.sh

Event: UserPromptSubmit (5s timeout)

Logs every user prompt as JSONL to logs/prompt-history.jsonl with timestamp, session ID, and working directory. Audit trail for all commands.

skill-nudge.sh

Event: UserPromptSubmit (5s timeout)

Pattern-matches user prompts against 16 regex patterns (5/15, content factory, morning brief, 1:1, WBR, 8 channel statuses, overdue, second opinion, what-if, system health). Injects a [SKILL NUDGE] message into Claude's context to route to the correct skill.

post-session-git-sync.sh

Event: Stop (30s timeout)

Auto-commits changes after each session. Stages tracked files (git add -u) plus known safe directories (CLAUDE.md, tasks/, docs/, skills/, config/). Generates timestamped commit message.

Scheduled Jobs (launchd)

Job	Schedule	Runner	Critical
daily-digest	Daily 07:00	parallel-morning-brief.py	Yes
weekly-battle-rhythm	Monday 07:00	parallel-wbr.py	Yes
weekly-515	Thursday 16:00	skill: "check 5/15"	No
friday-sweep	Friday 07:00	skill: "overdue task sweeper"	No
meta-audit	Monday 07:30	skill: "audit spend"	No
meeting-notes	Every 2 hours	auto-process-notes.py	No
monitor	Daily 18:00	monitor-jobs.sh	Yes

13 5/15 Intelligence Pipeline

A complete intelligence pipeline for processing weekly 5/15 reports from direct reports and skip-level reports.

Data Files (Company/Assistant/data/515/)

Pattern	Description	Count
`5-15_Feedback_YYYY-MM-DD.{md,html}`	Weekly feedback for all direct reports	8 files
`5-15_Josef_Buryan_YYYY-MM-DD_DRAFT.md`	Josef's own weekly 5/15 draft for CEO	6 files
`CMO_Direct_Feedback_YYYY-MM-DD.md`	CMO-level direct report feedback	3 files
`STEAM_515_Briefing_YYYY-MM-DD.md`	S-Team briefing summaries	2 files
`Steam_5-15_Review_YYYY-MM-DD.md`	S-Team 5/15 review	2 files
`skip-level-mapping.yaml`	Maps -2 reports to their managers with Asana GIDs	1 file
`intel_515.db`	SQLite database (1MB) -- people, submissions, metrics, search	1 file
`monitor_515.py`	Background polling script for submission changes	1 file
`attachments/`	Downloaded Asana attachments (screenshots, images)	10 files

Skip-Level Mapping

14 Project Foundry Module

Support module for tracking Groupon's Marketing Department AI transformation. Does NOT build agents -- it tracks progress, surfaces risks, and prepares communications.

Metric	Current	Target	Delta
Headcount	81	48	-33 (3 waves)
Operating Cost	$6.86M	$4.62M	-$2.24M (-32.6%)
Agents Deployed	--	75	33 autonomous + 42 on-demand
Workflows Mapped	--	232	44 full-auto, 169 AI-assisted, 17 manual

File	Purpose
targets.yaml	HC, cost, and agent deployment targets by team and quarter
team-plans.yaml	Sub-department mini-plans with current/future state
agent-registry.yaml	All 75 planned agents with deployment status (19K)
initiative-tracker.yaml	All initiatives with timeline, HC impact, status

15 Other Subprojects

Company/

Directory	Description
Marketing Analytics	Multi-agent marketing analytics pipeline. Output symlinked to Assistant data/input/analytics/. Major project (~16K last session cost).
Meeting Notes Processor	Auto-processes meeting notes. Output symlinked to Assistant data/input/meeting-notes/. Runs every 2 hours.
Meta-Ads	Meta Ads audit module. Weekly Monday 07:30 schedule.
AI-UGC-Video	UGC video generation project. Has CLAUDE.md (7K), RESEARCH.md, config/, data/, .venv.
AI-News-Monitor	AI news monitoring tool.
Paid-Media	Paid media analysis.
Project Foundry	Separate from the Foundry support module -- likely the actual transformation deliverables.

Personal/ (contents excluded per instruction)

16 Data Flow

EXTERNAL SYSTEMS ___________________________ | | Google Calendar | Asana | Tableau | BigQuery | Notion | Gmail | | | | | | (MCP tools) (asana_api.py) (MCP) (MCP) (MCP) (MCP) | | | | | | v v v v v v +-------------------------------------------------------------------------+ | VIRTUAL JOSEF (Claude Code) | | | | Command Pipeline (15 steps) | | 1. Receive -> 2. Classify -> 3. Depth -> 4. Entities -> 5. Blocking | | 6. Resolve refs -> 7. Memory -> 8. Feedback -> 9. Tools -> 10. Fetch | | 11. Generate -> 12. Validate -> 13. Format -> 14. Strip -> 15. Stop | | | | Reads: memory/, shared/config/, data/input/, templates/ | | Writes: data/515/ (feedback, drafts), memory/ (updates) | +-------------------------------------------------------------------------+ | | | | v v v v results/ reports/ data/515/ stdout (artifacts) (artifacts) (feedback, drafts) (user output) DATA INPUT ROUTES (shared/config/data-routes.yaml): Marketing Analytics output/latest --symlink--> data/input/analytics/ Meeting Notes Processor data/output --symlink--> data/input/meeting-notes/ Manual CSV/JSON exports ---------> data/input/{wbr,performance,ad-hoc}/ Google Sheets (pending) --WebFetch--> (in-session CSV parse) 5/15 PIPELINE: Asana subtasks --> asana_api.py --> ingest_515.py --> intel_515.db | +--------+--------+--------+ | | | | analytics search review-1s write-my-515 | | | | reports queries feedback Josef's draft

17 Project Memory (Claude Persistent)

Claude Code stores persistent memory in ~/.claude/projects/{project-path}/memory/. These survive across sessions and are auto-injected into context.

Main Project Memory (-Users-jburyan-Documents-Claude)

5/15 Project Memory (-Users-jburyan-Documents-ClaudeCode-5-15)

Other Project Memories

Plugins

Generated by Claude Opus 4.6 | /Users/jburyan/Documents/Claude/reports/system-architecture.html

File	Purpose
MEMORY.md	Index: links to 3 feedback memories for 5/15 processing
feedback_515_autoprocess.md	Rule: always auto-integrate completed 5/15 submissions without asking
feedback_515_tone.md	Rule: write 5/15 feedback in Josef's voice -- short, question-focused, no analyst style
feedback_515_ai_examples_links.md	Rule: AI Examples in 5/15 must always include links

File	Purpose
MEMORY.md	Submission status rules, formatting (plain text only), persistent file descriptions
direct_reports.md	Asana GID mapping for fast subtask lookups
open_questions.md	Carry-forward questions tracker per person per week (15K)
weekly_metrics.md	WoW metric tracking, stale data detection (24K)
weekly_template.md	Draft skeleton for new weeks