# SwarmAI -- Product Context

## Vision

SwarmAI is a live experiment proving that one builder + AI can operate at team scale. Human directs, AI delivers — coding, content, strategy, and operations through self-evolving systems and compound knowledge.

Human directs. AI delivers.

## What Makes SwarmAI Different

Most AI assistants are stateless -- every conversation starts from scratch. SwarmAI is designed around **persistent context** and a **self-growing intelligence core**.

- **Swarm Core Engine** -- Six interconnected flywheels (Self-Evolution, Self-Memory, Self-Context, Self-Harness, Self-Health, Self-Jobs) that feed each other. Every session makes the next one better. Every correction prevents a class of future mistakes.
- **Memory that persists** -- 3-layer pipeline (DailyActivity -> distillation -> MEMORY.md) with LLM-powered weekly pruning. Git-verified accuracy. Decisions, lessons, and preferences survive across sessions.
- **Skills that compound** -- 50+ built-in skills, and Swarm builds new ones when it hits capability gaps. Skills improve from usage.
- **Autonomous Pipeline** -- 9-stage lifecycle (EVALUATE -> THINK -> PLAN -> BUILD(TDD) -> REVIEW -> TEST -> ADVERSARIAL -> DELIVER -> REFLECT) with ROI gate, decision classification, and delivery gate. From one-sentence requirement to PR-ready delivery.
- **Projects that accumulate knowledge** -- DDD documents (PRODUCT.md, TECH.md, IMPROVEMENT.md, PROJECT.md) give Swarm autonomous judgment: Should we? Can we? Have we tried? Should we now?
- **Proactive intelligence** -- Session briefings with health alerts, signal highlights, temporal awareness, and learning patterns. Swarm doesn't wait to be asked.
- **Three execution modes** -- Direct (bug fix), TDD-only (clear scope), Full Pipeline (new architecture). Right process for right task.

## Swarm Core Engine -- The Heart of SwarmAI

The Core Engine is what makes SwarmAI compound value instead of just responding to prompts. Six interconnected flywheels that feed each other -- every session makes the next one better, every correction prevents a class of future mistakes, every piece of knowledge strengthens the whole system.

| Flywheel | Purpose | Feedback Signal |
|----------|---------|-----------------|
| **Self-Evolution** | Learn from corrections, build skills, capture competence | Correction count plateaus (same mistake never repeated) |
| **Self-Memory** | Remember what matters, forget what doesn't, verify accuracy | Memory token count stays bounded, distillation accuracy improves |
| **Self-Context** | Right information, right time, right budget | L1 cache hit rate, prompt relevance |
| **Self-Harness** | Validate brain accuracy, detect drift, auto-fix | Daily health pass rate trends to 100% |
| **Self-Health** | Monitor services, diagnose issues, alert and remediate | Service uptime >99%, error rate trends to zero |
| **Self-Jobs** | Automate background work -- signals, maintenance, user tasks | Job success rate, signal relevance |

**The Compound Loop:**
```
Session happens -> Memory captures -> Evolution detects patterns
-> Harness verifies accuracy -> Context assembles smarter prompts
-> Next session performs better -> (loop accelerates)
```

**Design Principles:**
1. Product-level, not workspace-level -- if essential, it belongs in `backend/`
2. Flywheels, not features -- every component feeds at least one other
3. Feedback over action -- acting without learning is just automation
4. Best outcome, not cheapest path -- LLM maintenance where judgment is needed
5. Bounded growth -- pruning is as important as adding
6. Git is truth -- memory claims must be verifiable against git log

## Strategic Priorities

1. **Core Engine** -- The six flywheels are the product's moat. Every sprint should strengthen at least one flywheel and close at least one feedback loop. Token cost is not the constraint; outcome quality is.
2. **Core stability** -- Multi-session architecture, resource management, streaming reliability. Nothing else matters if the foundation isn't solid.
3. **Self-evolution** -- Memory pipeline, proactive intelligence, signal processing, skill ecosystem. Swarm should get better at helping you without you telling it to.
4. **User experience** -- Fast iteration cycles, clear error messages, intuitive UX. The tool should disappear into the workflow.
5. **Autonomy progression** -- From AI-Assistant (Phase 1) to AI-Driven (Phase 2) to AI-Management (Phase 3). Gradual trust-building, not a cliff.

## Success Criteria

- Sessions never crash or lose context unexpectedly
- Swarm remembers decisions and lessons across sessions without being told
- New skills can be created by Swarm in under 30 minutes
- Users spend more time doing, less time re-explaining
- Context compounds: session 50 is meaningfully more productive than session 5

## Non-Goals

- **Not a cloud SaaS** -- Desktop-first, local-first. Your data stays on your machine.
- **Not a general chatbot** -- Opinionated, workspace-scoped. Built for people who ship, not people who chat.
- **Not code-only** -- Handles research, writing, communication, planning, scheduling. A full teammate, not a coding copilot.
- **Not a framework** -- SwarmAI is a product. It has opinions about how AI assistance should work.

## Target Users

All Knowledge-Workers, Developers and Leaders who want an AI teammate, not an AI tool. People who work across multiple projects, value accumulated context, and prefer action over conversation.

## Autonomy Phases

| Phase | Name | Essence | Human Role |
|-------|------|---------|-----------|
| 1 | AI-Assistant | Human decides, AI executes | Direct every task |
| 2 | AI-Driven | AI proposes, human approves | Review and approve |
| 3 | AI-Management | AI decides + evolves, human triages | Intervene when needed |

SwarmAI is currently transitioning from Phase 1 to Phase 2.
