WorkOS — Your Private AI Work OS

A portable, file-based work operating system you drive with an AI agent — Claude Code, Claude Cowork, or any agent that can read your files. Clone it, fill in your context, and it becomes your Work OS, with a clean separation between an anonymous, reusable instruction layer and your private context.

Built as a teaching template for professional knowledge workers. Use it as-is, or fork it and make it your own.

Contents

• Why
• What's inside
• Repository structure
• Quick start
• How it works
• Works with
• Skills & agents
• Optional: Obsidian / OKF knowledge wiki
• Verifying the install
• For educators & students
• Privacy & safety
• Contributing
• License
• Author & acknowledgements

Why

Most people use AI in one-off chats. A Work OS gives the AI a durable place to stand: it knows who you are, where things live, how you like to work, and which repeatable procedures to run — so every session starts oriented instead of from zero. This repo is that scaffold, kept deliberately generic so it fits any knowledge worker and can be shared without exposing anyone's private data.

Two design rules make that possible:

• The instruction layer stays anonymous. CLAUDE.md, everything under .claude/, 07-agents/, 08-workflows/, and 05-templates/ never contain a name, company, client, email, or personal preference — so the same system is reusable by anyone.
• Your data lives only under 01-context/. You personalise the system by editing context files, never by editing instructions. Those working files are git-ignored, so personal data is never committed.

This split keeps the template shareable — it is not a restriction on you. Real names, clients, and preferences in 01-context/ are exactly what belongs there, not a leak. The anonymity rule governs only the instruction layer you might share or contribute back — not your everyday work.

What's inside

• 4 agents — research-analyst, knowledge-librarian, planner, quality-reviewer (portable specs in 07-agents/, Claude Code adapters in .claude/agents/).
• 6 skills — capture-and-classify, research-synthesis, meeting-to-actions, planning, decision-record, weekly-review (.claude/skills/).
• 10 commands — capture, process-inbox, daily-briefing, prepare-meeting, weekly-review, audit-workos, privacy-check, and the knowledge-base trio ingest, query-knowledge, lint-knowledge (.claude/commands/).
• 4 workflows — with explicit approval points and dry-run defaults (08-workflows/).
• A "Session protocol" in CLAUDE.md that tells any agent how to orient and which skill to use.
• Privacy & structure tooling — scripts/privacy_check.py, scripts/validate_structure.py, and a runnable test suite (tests/).
• An optional Obsidian/OKF knowledge wiki scaffold under 04-knowledge/.
• Setup guides for building, extending, and wiring the OS to any Claude surface (setup/).

Repository structure

WorkOS/
├── CLAUDE.md            # anonymous operating manual (auto-loaded by Claude Code)
├── AGENTS.md            # pointer to CLAUDE.md
├── 00-inbox/            # unprocessed capture
├── 01-context/          # YOUR context (only *.example.* templates ship; real files git-ignored)
├── 02-areas/            # ongoing responsibilities
├── 03-projects/         # active / waiting / archive
├── 04-knowledge/        # durable knowledge (optionally an OKF/Obsidian wiki)
├── 05-templates/        # reusable, anonymous templates
├── 06-decisions/        # decision records
├── 07-agents/           # portable agent specifications
├── 08-workflows/        # multi-step processes with approval points
├── 09-outputs/          # drafts / final deliverables
├── 10-archive/          # inactive material
├── .claude/             # agents · skills · commands · settings
├── scripts/             # privacy_check.py · validate_structure.py
├── setup/               # SETUP.md · LLMWIKI.md · custom-instructions.md · templates · verify.py
└── tests/               # structure / anonymity / routing checks

Quick start

1. Get the repo — click “Use this template” on GitHub, or:

   git clone https://github.com/CoachSteff/WorkOS.git
   cd WorkOS

2. Create your context files from the shipped templates:

   # macOS / Linux
   cd 01-context
   for f in profile roles priorities preferences terminology projects lessons; do cp "$f.example.md" "$f.md"; done
   cp protected-terms.example.txt protected-terms.txt
   cd ..

   # Windows (PowerShell)
   cd 01-context
   foreach ($f in 'profile','roles','priorities','preferences','terminology','projects','lessons') { Copy-Item "$f.example.md" "$f.md" }
   Copy-Item protected-terms.example.txt protected-terms.txt
   cd ..

   Then fill in 01-context/profile.md, preferences.md, etc. (These working files are git-ignored.)
3. Point your AI agent at it:
   • Claude Code — open the folder as a project; CLAUDE.md auto-loads and its Session protocol runs every session. Nothing else to do.
   • claude.ai / Desktop / Cowork — paste the thin master prompt from setup/custom-instructions.md into Claude’s Custom Instructions (set your Work OS path once).
4. Verify (see below).

Building one from scratch, or teaching an agent to? See setup/SETUP.md.

How it works

At the start of any substantive task, the agent follows the Session protocol in CLAUDE.md: read the manual → read the narrowest relevant 01-context/ file → skim 01-context/lessons.md for past corrections → then use the right skill for the job. Behaviour is version-controlled in CLAUDE.md, so you improve the whole system by editing one file — never by rewriting a long prompt in a settings box.

Works with

The Work OS is just files and Markdown, so it runs with any AI agent that can read your files:

• Claude Code — first-class. It auto-loads CLAUDE.md and can use the native .claude/ slash commands and subagents. Nothing to configure.
• Claude Cowork — add the Work OS folder to your Cowork workspace and paste the master prompt from setup/custom-instructions.md into Custom Instructions. The Session protocol, your 01-context/, the skills, and the workflows all apply.
• claude.ai / Desktop — the same master prompt; if the surface can't read files directly, it asks you to paste the relevant one.
• Other agents & automation (MCP, n8n, local models) — point them at the same files.

The .claude/ folder adds Claude Code-native conveniences (slash commands, subagents). On other surfaces the same procedures live as the skills (.claude/skills/, SKILL.md) and workflow specs (08-workflows/) the agent reads — so behaviour carries across even where the slash-command UI doesn't exist.

Skills & agents

Situation	Use
Unsorted item to file	capture, then process-inbox
A source to turn into durable knowledge	ingest
A question the knowledge base may answer	query-knowledge
Knowledge base health check	lint-knowledge
A question needing sources	research-analyst / research-synthesis
Meeting notes → actions	meeting-to-actions
Turn a goal into a plan, agenda, or outline	planner / planning
A choice worth remembering	decision-record → 06-decisions/
Tidy or reorganise the OS	knowledge-librarian
Final check before sharing	quality-reviewer
Weekly reset and plan	weekly-review

Optional: Obsidian / OKF knowledge wiki

04-knowledge/ ships as an empty, ready-to-fill LLM Wiki using the Open Knowledge Format (OKF), openable as an Obsidian vault. To build or extend it, follow setup/LLMWIKI.md and validate with python3 setup/verify.py 04-knowledge WorkOSWiki. If you don’t want it, ignore 04-knowledge/ — the Work OS works without it.

Verifying the install

python3 scripts/validate_structure.py    # folder tree + required files present
python3 scripts/privacy_check.py         # no personal data in the anonymous instruction layer
python3 tests/run_tests.py               # structure + privacy + scanner self-test + template drift

Windows / Python: if python3 isn’t found, use python. The scripts use only the Python 3 standard library and relative paths, so they run identically on macOS, Linux, and Windows.

The structure check is handy any time. The privacy scan matters most before you share your instruction files or contribute upstream — for your own daily use you can skip it.

For educators & students

This repo is a GitHub template — click “Use this template” to get your own copy with a clean history, then work through setup/SETUP.md. Nothing here contains anyone’s personal data; each learner fills in their own 01-context/, which stays private on their machine.

This is your instance — put your real context in 01-context/ and use it freely. The anonymity rules exist only to keep the template reusable for the next person; they don’t police your own data, and you won’t trip over privacy warnings during normal daily use.

Privacy & safety

• Personal data never ships. Only 01-context/*.example.* templates, the README, and examples/.gitkeep are tracked; your filled-in files are git-ignored.
• Anonymity is checkable — when you need it. Planning to share your instruction files or contribute upstream? scripts/privacy_check.py scans the instruction layer (never your 01-context/) for leaked emails, tokens, home paths, and any terms you list in 01-context/protected-terms.txt. It’s an optional pre-share check, not daily hygiene.
• Safe by default. The agent does read-only work and drafts freely, but sending, publishing, purchasing, deleting, or any external side effect requires your explicit approval (see the approval policy in CLAUDE.md).
• No secrets in the repo. Credentials belong in your OS keychain, a credential manager, or a connector’s own auth.

Contributing

Issues and pull requests are welcome — improvements to the generic instruction layer, agents, skills, workflows, templates, or docs. Please keep every contribution anonymous: no personal names, companies, clients, or private examples in any instruction file (personalisation belongs in 01-context/, which is git-ignored). Run python3 tests/run_tests.py before opening a PR.

License

Licensed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0) — see LICENSE.

You may share and adapt this material, including commercially, as long as you:

• give appropriate credit to the original author, Steff Vanhaverbeke, link to the license, and indicate changes; and
• license your adaptations under CC BY-SA 4.0 (ShareAlike / copyleft).

Suggested attribution:

Based on WorkOS by Steff Vanhaverbeke, licensed under CC BY-SA 4.0.

Author & acknowledgements

Created by Steff Vanhaverbeke — github.com/CoachSteff.

Built to be driven by Claude — via Claude Code, Claude Cowork, claude.ai, or any file-capable agent. The optional knowledge wiki draws on the Open Knowledge Format and Andrej Karpathy’s “LLM wiki” idea.