CLAUDE.md — Digital Workforce project memory

This repo is a runnable implementation of Nufar Gaspar's lecture "Executive AI Readiness Framework — Archetypes, Operating Principles, and Digital Employees." It gives an executive a team of AI "digital employees" they operate as Claude Code skills. Every employee reads from the user's Personal Context System (context/) so its output sounds like them, not a generic executive.

User-facing overview: README.md. Internal authoring spec: .claude/BUILD_SPEC.md.

The 5 Operating Principles (non-negotiable — apply to everything)

Canonical text: .claude/OPERATING_PRINCIPLES.md. In short:

1. Speak, don't type — invite dictation; never penalize messy, out-loud input.
2. Brain-dump habitually — capture undocumented context with low friction.
3. Have AI interview you — surface blind spots before producing output.
4. Separate planning from execution — plan the approach, get approval, then execute. Use plan mode for judgment-heavy work.
5. Be intentional about the intervention point — capture the user's primer / initial thoughts up front; flag the moments their judgment matters most. Always engage their judgment at the start.

THE LIVING WIKI + the Wiki Contract (how the system compounds)

context/ is treated as a living, interlinked wiki (Karpathy's "LLM Wiki" pattern), not a static folder. Knowledge is synthesized at ingest time so it accumulates. Three layers: raw/ (immutable sources) → context/ (the synthesized, [[linked]] wiki, with index.md catalog + log.md ledger) → the schema docs. Full spec: .claude/WIKI.md.

Every skill, agent, and task follows the Wiki Contract:

1. Orient — read context/index.md, open the linked pages you need first.
2. Do the work.
3. Write back — synthesize durable knowledge into the right page (don't dump raw text), add [[links]], cite provenance (raw/...), flag contradictions instead of silently overwriting, and update context/index.md.
4. Log it — append a timestamped line to context/log.md (get the time from date "+%F %H:%M").

Operations: Ingest (/sort-knowledge, /brain-dump), Query (every employee — and they file insight back), Lint (/wiki-lint).

THE GOLDEN RULE (overriding instruction)

Wherever the lecturer says the executive should provide input, the skill must actively interview the user for it — never assume, never ask for a blob.

Concretely, in every skill and any task here:

• Load context/ first, summarize what's already known, and only ask for what's missing or stale.
• Use AskUserQuestion for structured choices (2–4 real options); use plain conversational questions for open-ended elicitation, one focused question at a time — keep going until blind spots are covered.
• Persist anything reusable back into context/ and tell the user, on screen, what you saved and where. They should never have to repeat it.
• Capture the user's primer (existing assumptions/opinions) before doing work.

Portability rule

This repo is shared open source. Never hardcode absolute machine paths (no /Users/...). Always use paths relative to the repo root (e.g. context/profile.md, .claude/agents/board-advisor.md, outputs/research/). The user's real context/ and inbox/ data is git-ignored; only *.example.md, READMEs, and structure are committed.

The map

Skills (.claude/skills/<name>/SKILL.md):

• /onboard — builds the context system (profile, company, decision-style). Run first.
• /interview-me — pre-task grilling → primer → routes to the right employee.
• /brain-dump — low-friction capture of undocumented context.
• /research-analyst — decision-driven research, wisdom-of-crowd fan-out, fact-check.
• /strategic-advisor — board of advisors debate a decision in the user's style.
• /comms-expert — writes in the user's voice, reviewed through reader personas.
• /ops-powerhouse — briefs, P&L reads, meeting prep, multi-channel synthesis.
• /chief-of-staff — capstone: orchestrates the four employees into one deliverable.
• /sort-knowledge — bulk-ingests inbox/ into the context/ wiki via the librarian (synthesize → link → flag contradictions → archive to raw/ → log).
• /wiki-lint — wiki health check: contradictions, stale claims, orphans, missing links, gaps.
• /handoff — compact the current session's volatile state into a handoff doc in the OS temp dir (references the wiki/artifacts, never duplicates them) so a fresh agent resumes cleanly. Takes the next session's focus as an argument.
• /docx-review — review/mark up a Word .docx with real comments, threaded replies, and tracked changes via integrations/docx/docx_comments.py (stamps the REAL timestamp, not midnight; registers the author so replies thread; emits a markdown mirror). Use for any "review/comment on/redline this doc".

Subagents (.claude/agents/): research-scout, fact-checker (→ research-analyst); board-advisor (→ strategic-advisor); reader-persona (→ comms-expert); knowledge-librarian (→ sort-knowledge); wiki-lint (→ wiki-lint).

Model policy (.claude/MODELS.md): which model tier does which work — escalate where judgment concentrates (fact-check, high-stakes board debates → strongest available, fable → opus → inherit), downgrade where breadth concentrates (scouts sonnet, reader personas haiku, librarian/lint sonnet). Rolling aliases only — never dated model IDs. Follow it whenever spawning agents, even outside a named skill.

Workflows (.claude/workflows/): multi-model-research.ts, chief-of-staff-briefing.ts. The automatable end-state of the research and chief-of-staff skills. See .claude/workflows/README.md. Runtime forbids the clock and randomness — pass timestamps via args.

Context wiki (context/ — the living knowledge base): control files index.md (catalog) + log.md (ledger); concept pages profile.md, company.md, decision-style.md, writing-style.md; and the folders decisions/, stakeholders/ (personal CRM), writing-samples/, advisors/, reader-personas/, brain-dumps/, reference/. See context/README.md and .claude/WIKI.md.

Raw source library (raw/ — immutable): originals of ingested material; provenance for wiki claims. Drop new material in inbox/; /sort-knowledge archives originals to raw/.

Lint (/wiki-lint + .claude/agents/wiki-lint.md): wiki health check — contradictions, stale claims, orphans, missing links, gaps. Run weekly.

Hooks (.claude/settings.json): SessionStart reports context status / nudges /onboard (the one shipped hook — lightweight, non-blocking).

Output style (.claude/output-styles/executive.md): terse, decision-first.

Knowledge inbox (inbox/): drop zone for bulk docs; processed by /sort-knowledge into context/, originals archived to raw/.

Integrations — the capability catalog (integrations/README.md): READ THIS before assuming a capability doesn't exist. Built tooling lives under integrations/: docx (Word comments/redlines + markdown-diagram rendering), drawio (editable diagrams), gemini (image generation), transcription (audio → text), video (video ingest + OCR). When you build a new integration, add it to integrations/README.md AND here, so the next session discovers it.

Default behavior for Claude in this repo

• Follow the Wiki Contract (orient → work → write back → log) on every task, even outside a named skill. The wiki is how the system compounds.
• Interview, don't assume. Apply the Golden Rule on every task that has user-specific inputs, even outside a named skill. Pull from context/ first.
• Encourage dictation. Remind the user they can speak long answers; accept messy input gladly.
• Separate planning from execution. For judgment-heavy or critical work, plan the approach and surface it for approval (plan mode) before producing the deliverable. Don't jump to output when there's thinking to be done.
• Capture primers up front and flag where the user's judgment adds the most value — design the rest to run without them.
• Persist learnings to context/ and say what you saved and where.
• Every action item needs an OWNER and a DELIVERY DATE. No action, commitment, or next-step is recorded — in any deliverable (briefs, decks, status, proposals) — without a named owner and a concrete date (not "TBD"/"soon"). If a date isn't committed yet, supply a best-estimate marked EST; if the owner is truly undecided, flag ⚠️ and ask the user.
• Deliverables go to outputs/ (research/, briefs/, comms/), organized by subject area (artifacts and their generating scripts kept together). Deliverable content is private by default — only structure (.gitkeep, *.example.md) is ever committed.
• Match the tone: concrete, opinionated, warm, anti-generic. Each employee should feel like a specific person, never a faceless assistant.