CLEAR Context OS

Context Engineering for Claude Code
Organize what you know. Build what's missing. Keep it alive. Let it learn.

Quick Start  •  How It Works  •  Skills & Agents  •  Installation  •  Getting Started Guide

Your AI had perfect context — two weeks ago. Since then your strategy shifted, your processes changed, you had three meetings that redefined your priorities, and your personal operating context evolved. But your AI is still working from the old picture.

CLEAR Context OS doesn't just organize your knowledge. It engineers it — with ownership boundaries that prevent drift, a self-learning system that gets smarter every session, and strategic reflection that catches what maintenance misses. Think of it as a living wiki + memory system that Claude Code maintains alongside you.

The Problem: Context Rot

Everyone using AI hits the same wall:

Context rot is the silent degradation of AI context over time. It happens to everything — business strategy, personal SOPs, process docs, competitive intelligence, team knowledge, even your own priorities and operating context.

It happens because:

• No ownership — Same info lives in 5 files, each slightly different. Which is right?
• No boundaries — Brand voice bleeds into messaging, strategy contradicts the pitch deck, your personal notes conflict with the team docs
• No maintenance — Context was set up once and never revisited
• No learning — Same mistakes repeated because nothing was captured

The cost: Every decision based on stale context compounds the problem. You lose trust in AI and fall back to doing everything manually.

The misconception: "Just give AI more data." But more data without structure creates more confusion, not less. Five files saying slightly different things about your pricing is worse than one file that's right. Context engineering isn't about volume — it's about accuracy, ownership, and maintenance.

The Solution: CLEAR Context Engineering

CLEAR Context OS is a complete system — methodology, skills, templates, and automation — for building a knowledge architecture that stays accurate as everything around it changes. It works for business knowledge, personal operating context, SOPs, competitive intelligence, team processes — anything that needs to stay current.

🚀 Quick Start

Option A: New project (easiest)

Click "Use this template" on GitHub. You get everything — skills, templates, hooks, folder zones. Open Claude Code and go.

Option B: Add to existing project

git clone https://github.com/walm00/business-context-os.git /tmp/bcos
cd /path/to/your/project
bash /tmp/bcos/install.sh

Then tell Claude about your business:

Starting fresh? "I want to set up my business context. Here's my website: [url]" — or share a pitch deck, LinkedIn page, or just describe what you do.

Already have docs? "Scan my repo and show me what business context already exists."

Claude reads what you share, drafts your first 3 data points, and you review. 20-30 minutes to working context. See the Getting Started Guide for the full walkthrough.

🔧 How It Works

The CLEAR Methodology

Five principles that prevent context rot. Each one addresses a specific failure mode:

Document Types

Any knowledge that needs to stay accurate — business, personal, operational, strategic:

The Metadata Standard

Every managed document has YAML frontmatter that enables automated tracking, auditing, and enforcement:

---
name: "Company Value Proposition"
type: context
cluster: "Strategy & Positioning"
version: "1.2.0"              # Bump on EVERY change
status: active                 # draft | active | under-review | archived
created: "2026-01-15"         # Set once, NEVER change
last-updated: "2026-04-05"    # MUST update on every edit
---

The rule: Every edit = update last-updated + bump version. No exceptions. A PostToolUse hook automatically validates this when Claude edits your docs.

The Folder Structure

docs/
├── *.md                 # Active context — current reality. Claude trusts this.
├── _inbox/              # Raw material — meeting notes, brain dumps. No quality bar.
├── _planned/            # Polished ideas — may or may not happen. Not yet real.
├── _archive/            # Superseded — kept for reference, not active.
├── table-of-context.md  # Business synthesis (update when things change)
├── current-state.md     # Operational priorities (update as often as needed)
└── document-index.md    # Auto-generated inventory

The folder IS the signal. When Claude finds docs/_planned/enterprise-pricing.md, it knows that's an idea — not reality — before opening the file.

Ownership Specification

The core of what prevents drift. Every document declares what it owns and what it doesn't:

DOMAIN: Customer-facing value statements and core differentiation framework

EXCLUSIVELY_OWNS:
- Primary value proposition statement
- Key differentiators (why us vs. alternatives)
- Benefit hierarchy (what matters most to customers)

STRICTLY_AVOIDS:
- Product feature details (see: product-overview)
- Pricing and packaging (see: pricing-model)
- Competitor analysis (see: competitive-positioning)

When two documents disagree, the ownership spec tells you which one is authoritative. No more "which version is right?"

🛠️ Skills & Agents

11 Skills for the Full Context Lifecycle

1 Agent

Enforcement & Automation

📦 What's In The Box

business-context-os/
│
├── docs/
│   ├── methodology/              # The CLEAR intellectual core
│   │   ├── clear-principles.md       # 5 principles with rationale
│   │   ├── context-architecture.md   # Knowledge structure + context window management
│   │   ├── ownership-specification.md # The 6 keywords that prevent drift
│   │   ├── document-standards.md     # Metadata, quality levels, versioning
│   │   └── decision-framework.md     # When to act, when to wait
│   │
│   ├── guides/                   # How to use it
│   │   ├── getting-started.md        # Week 1 walkthrough
│   │   ├── defining-your-context.md  # Step-by-step data point creation
│   │   ├── maintenance-guide.md      # Keeping context alive long-term
│   │   ├── scheduling.md            # Automated recurring maintenance
│   │   ├── migration-guide.md        # Moving from messy docs to CLEAR
│   │   ├── adoption-tiers.md         # Incremental adoption path
│   │   └── for-non-technical-users.md # Plain language, no jargon
│   │
│   ├── architecture/             # How it's built (for contributors)
│   │   ├── system-design.md          # Full system overview with Mermaid diagrams
│   │   ├── content-routing.md        # How content enters and flows
│   │   ├── component-standards.md    # How to build new skills/agents/hooks
│   │   ├── metadata-system.md        # All validation rules in one place
│   │   └── maintenance-lifecycle.md  # Scheduled rhythms and trigger chains
│   │
│   ├── templates/                # Fill-in-the-blank starting points
│   │   ├── context-data-point.md     # Single document template
│   │   ├── context-cluster.md        # Group related documents
│   │   ├── context-architecture-canvas.md  # Full architecture planning
│   │   ├── table-of-context.md       # Business synthesis template
│   │   ├── current-state.md          # Operational priorities template
│   │   └── maintenance-checklist.md  # Weekly/monthly/quarterly checks
│   │
│   ├── _inbox/                   # Raw material landing zone
│   │   └── sessions/             # Auto-captured session context (hooks)
│   ├── _planned/                 # Polished ideas, not yet active
│   └── _archive/                 # Superseded documents
│
├── .claude/
│   ├── skills/                   # 11 skills (see above)
│   ├── agents/                   # 1 agent (explore)
│   ├── hooks/                    # 3 hooks: frontmatter check, commit check, session capture
│   ├── quality/ecosystem/        # State, config, lessons (self-learning)
│   ├── scripts/                  # Index builder, maintenance, cross-ref analysis
│   └── registries/               # Entity registry, reference indexes
│
├── examples/
│   └── brand-strategy/           # Complete worked example
│       ├── context-architecture.md   # Architecture for a brand team
│       └── data-points/             # 8 realistic data points (Acme Co)
│
├── CLAUDE.md                     # Claude Code instructions + session bootstrap
├── install.sh                    # Installer for existing projects
└── LICENSE                       # MIT

📥 Installation

Option A: New Project

Click "Use this template" on GitHub. Everything is ready — folder zones, skills, templates, hooks.

Option B: Existing Project

# Clone BCOS
git clone https://github.com/walm00/business-context-os.git /tmp/bcos

# Go to YOUR project
cd /path/to/your/project

# Install (never overwrites existing files)
bash /tmp/bcos/install.sh

The installer copies skills, agents, docs, templates, hooks, and scripts. Creates _inbox/, _planned/, _archive/ folder zones. If you already have a CLAUDE.md, it saves a reference copy for manual merge.

Option C: Manual

Copy .claude/, docs/, and examples/ into your project. Merge CLAUDE.md into your existing one.

Verify

bash .claude/skills/skill-discovery/find_skills.sh   # Should show: 11 skills
bash .claude/agents/agent-discovery/find_agents.sh   # Should show: 1 agent

🔄 Updating

When a new version is released, pull the latest framework files without touching your business context.

If you cloned the repo (most common):

git pull

If you forked the repo:

git fetch upstream
git merge upstream/main

After your first pull, use the update script for all future updates — no git knowledge needed:

python .claude/scripts/update.py            # interactive, shows what changed
python .claude/scripts/update.py --dry-run  # preview only, applies nothing
python .claude/scripts/update.py --yes      # apply without confirmation prompt

The script updates only framework files (skills, agents, hooks, scripts, methodology docs, templates, examples). It never touches:

• docs/*.md — your business context
• docs/_inbox/, _planned/, _archive/ — your working material
• .private/ — your private docs
• CLAUDE.md — shown as a diff, you decide what to apply

Downloaded a zip instead of cloning?

# Download the latest zip and extract it, then point the script at it:
python .claude/scripts/update.py --local /path/to/extracted-zip

⏰ Scheduled Maintenance

Context that isn't maintained rots. Set up recurring tasks so Claude keeps your knowledge alive:

These frequencies adapt by phase. See scheduling.md for phase-specific rhythms and ready-to-use prompts.

🎯 Who Is This For?

The system is role-agnostic. CLEAR methodology works the same whether you're managing investor materials, personal SOPs, or team onboarding docs.

🌱 Adoption Path

Start with Tier 1. Move to Tier 2 when manual maintenance feels like overhead. Extend with custom skills when you need more — the ecosystem-manager skill guides you through creating new tools.

💡 Philosophy

Living systems, not one-time setups. Your business changes. Your priorities change. Your knowledge evolves. Your AI context should evolve with it — structurally, not chaotically.

Order that maintains itself. CLEAR doesn't just organize your documents. It creates a system where drift is caught early, duplication is centralised, and every piece of knowledge has a clear home.

Self-learning. The lessons system captures what works and what doesn't. Your context architecture gets smarter with every maintenance cycle.

The same discipline everywhere. The ecosystem-manager applies CLEAR principles to your skills and agents themselves. The tools stay as ordered as the documents.

🤝 Contributing

Contributions welcome. Whether you've found a better way to structure context, built a useful skill, or improved the docs — open an issue or submit a PR.

Branch Strategy

For contributors: fork the repo, branch off dev, open your PR targeting dev. When dev is stable it gets squash-merged into main as a clean release.

Contributing via Lessons

The fastest way to improve BCOS is through lessons learned. As you use the system, it captures what works and what doesn't in .claude/quality/ecosystem/lessons.json. If you discover a pattern that would help everyone — a better way to structure a data point, a common mistake to avoid, a workflow improvement — you can contribute that lesson back.

How:

1. Use BCOS normally — lessons accumulate automatically
2. Review your lessons: look for ones that are universal, not specific to your situation
3. Open a PR with the lesson added to the repo's lessons.json
4. Include context: what happened, why it matters, what the lesson changes

This is the most natural contribution path — you're already generating insights by using the system.

Other Contributions

• New skills (maintenance workflows, context patterns)
• Examples for specific industries or functions
• Improvements to existing skills or methodology docs
• Better templates for context data points

For Contributors: Architecture Docs

If you want to understand HOW BCOS is built (not just how to use it), start with docs/architecture/system-design.md. The architecture docs explain design decisions, the skill graph, component standards, and why things are built the way they are.

📖 Origin

CLEAR Context OS was created by Guntis Coders after two years of building and operating context systems in production — first for competitive intelligence work, then for broader business context management.

The CLEAR methodology (Contextual Ownership, Linking, Elimination, Alignment, Refinement) emerged from a practical problem: AI context degrades silently over time, and no amount of one-time documentation prevents it. The solution required a system — not just documents, but ownership boundaries, automated maintenance, self-learning, and structured reflection.

The Table of Context concept — a living synthesis of what your business IS, distinct from the file inventory — was first articulated in a Medium article on business context engineering and became a core architectural pattern.

This isn't a theoretical framework. Every skill, every pattern, every architectural decision was tested in real-world use before being abstracted into this open-source package.

📄 License

MIT — Free to use, modify, distribute. No restrictions.

CLEAR Context OS
Context engineering for Claude Code.
Stop context rot. Start building knowledge that lasts.