Claude Operating System

A meta-framework for human-AI collaboration with Claude Code -- templates, skills, patterns, and enforcement mechanisms extracted from production AI builds.

The Problem

Human-AI collaboration at production scale has structural friction that better prompting alone cannot fix:

• Context evaporates between sessions. Every new session starts cold. The human re-explains architecture, constraints, and project state -- burning context window and patience.
• The human becomes the real-time quality layer. Without encoded constraints, the agent drifts. When a content extraction system processing 900+ items silently wastes most of its output, there was no specification telling it what "good" looked like.
• Work stays sequential when it could parallelize. Most sessions execute tasks one at a time, even when half the work is independent.
• Session quality is inconsistent. Some sessions produce clean handoffs; others end with undocumented state scattered across files.
• Knowledge stays locked in individual projects. When the same pipeline failure class appears for the third time across a different codebase, nobody notices because learnings were never extracted.

Building on Nate B. Jones' Four Prompting Disciplines, we identified that prompting is one of four skills -- and the one that matters least as agents grow more autonomous. The other three (context engineering, intent engineering, specification engineering) are where the real output gap lives.

The Friction Points We Addressed

Friction Point	What We Built
Re-explaining context each session	session-start skill loads project docs in cache-optimal order and proposes a parallel execution plan
Being the real-time quality layer	Constraint architecture in CLAUDE.md -- MUSTS, MUST NOTS, PREFERENCES, ESCALATION TRIGGERS
Sequential work when tasks are independent	Agent orchestration guide + session-start proposes parallel execution by default
Not knowing what Claude Code can do	Capability map organized by workflow stage
Inconsistent session quality	Session lifecycle protocol enforced by session-start and session-end skills
Context window exhaustion mid-session	Context monitor rule auto-closes sessions at ~50 tool calls and triggers Emergency Mode on compaction; hooks provide accurate counting (PostToolUse hook counts tool calls, PreCompact hook fires before compaction)
Knowledge locked in individual projects	Feedback loop skill reviews cross-project learnings and promotes recurring patterns

What's Inside

Category	Contents	Purpose
Templates (5)	CLAUDE.md, MEMORY.md, NEXT_SESSION_PROMPT, Learnings, Context Monitor Rule	Standardized project starters + rule templates
Frameworks (2)	Four Disciplines, Session Lifecycle	Conceptual models with practical checklists
Guides (2)	Capability Map, Agent Orchestration	What Claude Code can do, organized by workflow
Patterns (3)	Recurring Bugs, Architecture Patterns, Anti-Patterns	Cross-project wisdom from production AI builds
Skills (4)	session-start, session-end, new-project, feedback-loop	Enforcement mechanisms, globally installed
Hooks (2)	context-monitor.sh, pre-compact.sh	PostToolUse and PreCompact hooks for accurate tool-call counting

How to Use It

1. Starting a new project -- /new-project scaffolds from templates, giving every project a constraint architecture and session protocol from day one.
2. Starting any session -- /session-start loads context in cache-optimal order and proposes a parallel execution plan before work begins.
3. Ending any session -- /session-end enforces a 7-step documentation checklist (update CLAUDE.md, update MEMORY.md, create handover doc, write next-session spec, capture learnings, git commit, context budget report). Sessions auto-close at ~50 tool calls via the context monitor rule -- no manual invocation needed.
4. Every few sessions -- /feedback-loop reviews learnings across projects and surfaces recurring patterns worth documenting.
5. Capability discovery -- guides/CAPABILITY_MAP.md organizes what Claude Code can do by workflow stage.
6. Before building anything complex -- frameworks/FOUR_DISCIPLINES.md defines where effort should go beyond prompting.

Quick Start

git clone https://github.com/Sukrit-bit/claude-operating-system.git
cd claude-operating-system
chmod +x install.sh
./install.sh

This symlinks skills to ~/.claude/skills/ and hooks to ~/.claude/hooks/, then merges hook configuration into ~/.claude/settings.json -- so both skills and hooks work globally across every Claude Code project. After installation, /session-start, /session-end, /new-project, and /feedback-loop are available globally, and the PostToolUse and PreCompact hooks are active for accurate context counting. To use templates directly, copy them into a new project and adapt -- including templates/rules/context-monitor.md, which should be copied to .claude/rules/context-monitor.md in each project to enable automatic session-close at context budget thresholds. The rule provides the policy; the hooks provide the accurate tool-call count that drives it.

If the repo moves, re-run install.sh -- symlinks use absolute paths.

Credits and Further Reading

The Four Disciplines framework builds on Nate B. Jones' work on prompting disciplines, extending the model to cover context, intent, and specification engineering. See TECHNICAL.md for engineering decisions behind the skill architecture, template design constraints, and pattern classification methodology.

Built with Claude Code.