# Philosophy

Why we built Claude Copilot and the principles that guide it.

---

## The Problems We Solve

### For Solo Developers

Building software alone is hard. You're expected to be an expert in architecture, security, testing, UX, accessibility, DevOps, and more—all at once.

AI assistants help, but they have fundamental limitations:

**They forget everything between sessions.**
Every conversation starts from zero. You explain your project, your decisions, your context—again and again. Tokens wasted. Time lost. Momentum killed.

**They give generic advice.**
Ask about architecture and you get textbook answers. Ask about security and you get OWASP checklists. Nothing specific to your context, your constraints, your actual situation.

**They lack proven processes.**
Every response is ad-hoc. No consistent methodology. No quality gates. No structured approach to complex problems. Just... whatever comes out.

### For Teams

Teams face the same challenges at scale—plus new ones:

**Knowledge stays siloed.**
What one engineer learns doesn't transfer to others. The same problems get solved repeatedly, differently, inconsistently.

**Standards exist but aren't followed.**
Documentation sits in wikis nobody reads. Best practices live in heads, not systems. New hires slowly absorb "how we do things here" through osmosis.

**Onboarding takes months.**
Every new team member starts from scratch. They learn through trial and error what veterans know intuitively. Institutional knowledge walks out the door when people leave.

**AI amplifies inconsistency.**
Everyone prompts differently. Gets different quality. Makes different mistakes. The team multiplies its inconsistencies instead of converging on excellence.

### The Strategic Gap

Even when teams overcome these challenges, a bigger problem remains:

**Engineers build what's specified, not what's needed.**
Nobody advocates for the user during implementation. Requirements get implemented literally, not thoughtfully.

**Design and development speak different languages.**
Intent gets lost in translation. The gap between design and code widens with every handoff.

**Security, accessibility, and quality are afterthoughts.**
Bolted on at the end instead of built in from the start. Expensive to fix. Often skipped entirely.

**AI tools optimize locally, not globally.**
They help with the task at hand but miss the bigger picture. No one asks "should we be doing this at all?"

---

## Our Solution

Claude Copilot is an instruction layer for Claude Code.

It's not separate software — it's a collection of markdown files (agents, commands, project instructions) and two CLI tools (`cc` for memory and skills, `tc` for task management) that give Claude Code persistent memory, on-demand skills, and ephemeral task storage.

When you run Claude Code in a project with Claude Copilot, Claude reads these instructions and gains new capabilities:

| Capability | What It Does | How It Works |
|------------|--------------|--------------|
| **Memory** | Remembers across sessions | `cc memory` CLI + SQLite (FTS5 keyword search) |
| **Specialists** | Expert guidance for any task | 16 agent definitions (markdown) |
| **Known References** | Configured paths/refs surface into every session via the Known References registry; `cc memory` search is available manually — agents do not yet auto-search a company knowledge repo _(roadmap: agent auto-pull)_ | `cc config set refs.*` + UserPromptSubmit hook |
| **Skills** | Auto-fire from trigger-rich descriptions; code-bearing skills run scripts | Skill library; `cc skill` CLI as fallback |
| **Tasks** | Ephemeral work product storage | `tc` CLI (PRDs, tasks, work products) |
| **Protocol** | Consistent quality | Command definitions (markdown) |

---

## Design Principles

### Every Developer Deserves a Team

Solo developers shouldn't have to be experts in architecture, security, testing, UX, accessibility, DevOps, and documentation all at once.

Claude Copilot gives you access to specialized expertise when you need it. Not a replacement for human experts—but the next best thing when you're working alone at 2am.

### Human Advocates Have Equal Standing

The "Human Advocate" agents (Service Designer, Design) aren't secondary to technical agents.

Software exists to serve humans. These agents ensure that happens. They have equal authority, equal importance, equal voice in the process.

### Memory That Persists

Your context shouldn't evaporate between sessions.

Decisions, lessons, and progress persist so you never waste tokens rebuilding context. Pick up exactly where you left off, even weeks later.

### Skills on Demand

Load specialized knowledge when you need it, not as bloated context at the start of every session.

Skills auto-fire from their trigger-rich `description` field — the model surfaces them automatically when a prompt matches. `cc skill search` provides explicit fallback discovery (case-insensitive substring match). Your token budget goes to actual work, not background context.

### Your Standards, Not Ours

Claude Copilot ships with industry-standard methodologies—but your team isn't generic.

Override any agent with your architecture standards. Add skills encoding your API patterns. Non-developers can contribute too: your UX team's research methods, your content team's voice guidelines, your security team's compliance requirements.

The framework adapts to you. Not the other way around.

### Progressive Enhancement

Claude Copilot works immediately with zero configuration:
- Clone, build, setup, go
- No accounts required
- No external services needed
- Full functionality offline

External services (Skill Marketplace, PostgreSQL) add power but aren't required. Start simple, add capabilities as you need them.

### Git-Native Knowledge

Company knowledge should be:
- Version controlled (track changes)
- Reviewable (PRs for knowledge updates)
- Shareable (clone and go)
- Owned by you (not locked in a service)

That's why knowledge repositories are Git repos, not database entries.

---

## What Claude Copilot Is Not

**Not a replacement for Claude Code.**
It's an enhancement layer. Claude Code does the actual work. Claude Copilot provides instructions, memory, and skills.

**Not a proprietary platform.**
It's open source. Fork it. Modify it. Make it yours.

**Not a managed service.**
Runs entirely on your machine. Your data stays with you.

**Not magic.**
It's structured instructions that make Claude more effective. The quality still depends on Claude's capabilities and your guidance.

---

## The Vision

### What It Is Today

Claude Copilot gives individual developers and small teams a team of 16 specialist agents with strict points of view, a design-led process enforced by mechanical hooks, persistent memory across sessions, and real task/worker orchestration.

The design goal is more disciplined, resumable work built from the practices that tend to produce better software. We measure process and context efficiency, not output quality — there is no defect/rework data yet. The "Not magic" framing applies here too: structured instructions that make Claude's process repeatable and inspectable, not a guarantee of outcomes.

### The Direction

As AI capabilities grow, the instruction layer becomes more powerful:
- More sophisticated agents
- Deeper domain specialization
- Better cross-agent collaboration
- Richer memory and context

The architecture is designed to grow with AI capabilities while remaining simple to use and modify.

### The Goal

Every developer has access to a full team of specialists — not to replace human expertise, but to augment human capability.

The best practices of the best teams, encoded and available to everyone.

Your company's institutional knowledge, persisted and accessible.

Your standards, applied consistently across every project, every team member, every session.

---

## Contributing

Claude Copilot is open source because we believe these capabilities should be available to everyone.

When contributing:
- Keep base agents generic (no company-specific content)
- Use industry-standard methodologies
- Include routing to other agents
- Document decision authority

See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

---

## Credits

Built by [Everyone Needs a Copilot](https://ineedacopilot.com).

Because everyone does.
