Welcome to Harmony Framework! This guide will help you get up and running in minutes.
| Tool | Purpose | Install |
|---|---|---|
| Node.js 18+ | Runtime for npx | nodejs.org |
| jq | JSON processing | sudo apt install jq / brew install jq |
| yq | YAML processing | sudo apt install yq / brew install yq |
| Git | Version control | Pre-installed on most systems |
Harmony Framework requires these official MCP servers for cross-session learning and structured reasoning:
| MCP Server | Package | Purpose |
|---|---|---|
| server-memory | @modelcontextprotocol/server-memory |
Cross-session memory, Sentinel error patterns |
| server-sequentialthinking | @modelcontextprotocol/server-sequentialthinking |
Structured problem decomposition |
Configuration MCP Client (Claude Desktop / Cursor / VS Code):
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
},
"sequentialthinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequentialthinking"]
}
}
}- AI Assistant: Claude Code, Cursor, Windsurf, or similar
- Docker (for containerized development)
# Create a new project or navigate to existing one
mkdir my-project && cd my-project
# Install Harmony
npm install harmony-ai-framework
# Initialize Harmony in your project
npx harmony initDuring initialization, you'll be asked:
? Project name: my-project
? Language: English / Français
? Enable Guardian Protocol? Yes
? Enable Sentinel System? Yes
? Enable HQVF Quality? Yes
? Starting phase: Discovery (Phase 1)
npx harmony doctorExpected output:
✅ Harmony Framework v1.0.0
✅ Configuration valid
✅ Memory system initialized
✅ Hooks installed
✅ Agents available: 6 core, 4 specialists
✅ Ready to go!
Open your AI assistant and type naturally:
"analyze the requirements for a user authentication system"
Harmony's Guardian will:
- Detect intent: ANALYZE
- Route to: Analyst (Analyst)
- Create a brief document
"create the PRD for authentication"
Guardian detects: PLAN → Routes to PM
"design the authentication architecture"
Guardian detects: DESIGN → Routes to Architect
"create stories for the login feature"
Guardian detects: PLAN_STORY → Routes to SM
"create UCVs for STORY-001"
Guardian detects: CREATE_UCV → Routes to UCV Writer
"implement STORY-001"
Guardian:
- Checks if story exists ✅
- Checks if UCV is approved ✅
- Routes to Developer (Developer)
┌────────────────────────────────────────────────────────────────┐
│ HARMONY WORKFLOW │
├────────────────────────────────────────────────────────────────┤
│ │
│ You say: "develop the login feature" │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ GUARDIAN PROTOCOL │ │
│ │ ┌───────────────────────────┐ │ │
│ │ │ 1. Detect Intent │ │ │
│ │ │ → IMPLEMENT │ │ │
│ │ │ │ │ │
│ │ │ 2. Check Prerequisites │ │ │
│ │ │ → Story exists? ✅ │ │ │
│ │ │ → UCV approved? ✅ │ │ │
│ │ │ │ │ │
│ │ │ 3. Route to Agent │ │ │
│ │ │ → Developer (Developer) │ │ │
│ │ └───────────────────────────┘ │ │
│ └─────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ SENTINEL SYSTEM │ │
│ │ • Monitors for errors │ │
│ │ • Records in error journal │ │
│ │ • Triggers circuit breaker │ │
│ └─────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ DEVELOPMENT │ │
│ │ • Code implementation │ │
│ │ • UCV checkboxes marked │ │
│ │ • Tests written │ │
│ └─────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ QUALITY GATE │ │
│ │ • Exploratory QA explores │ │
│ │ • UCV Validator validates UCVs │ │
│ │ • Story marked DONE │ │
│ └─────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘
Harmony understands natural language. No need to memorize commands!
| You say... | Harmony understands... | Agent activated |
|---|---|---|
| "develop the login" | IMPLEMENT | Developer |
| "fix the bug" | FIX | Developer |
| "create a story" | PLAN_STORY | SM |
| "test the API" | TEST | Tester |
| "explore the UI" | EXPLORE_QA | Exploratory QA |
| "analyze requirements" | ANALYZE | Analyst |
| "design architecture" | DESIGN | Architect |
| "create UCVs" | CREATE_UCV | UCV Writer |
| "validate UCVs" | VALIDATE_UCV | UCV Validator |
Harmony understands both English and French:
English: "develop the scoring system"
French: "développe le système de scoring"
Both → Intent: IMPLEMENT → Developer Agent
- Installation Guide - Detailed installation options
- Core Concepts - Deep dive into Harmony's architecture
- Agents Guide - Learn about all available agents
- Patterns Reference - Design patterns library
- Prompt Monitor - Track and improve your prompts
- Examples - Real-world examples
Track your interactions and learn to write better prompts:
# Install Python dependencies (one-time)
pip3 install -r .harmony/tools/prompt-monitor/requirements.txt
# Start the dashboard
harmony monitor start
# Open in browser
harmony monitor open # → http://localhost:8080🛡️ GUARDIAN CHECKPOINT - VIOLATION
TENTATIVE: Code modification without active story
Solution: Create or activate a story first:
"create a story for [your feature]"
🛑 SENTINEL: Circuit Breaker OPEN
3 consecutive failures detected
Solution:
- Check the error journal:
npx harmony memory show errors - Fix the root cause
- Reset the circuit:
npx harmony sentinel reset
Solution: Check your current phase:
npx harmony status
Move to the appropriate phase or use an agent allowed in your current phase.
Need help?
Open an issue on GitHub or join our Discord community.