Archon Manager

What this skill does

# Archon Manager

**Master Archon MCP for strategic project management and knowledge operations.**

Archon is the command center for AI coding assistants, providing:

- **Strategic Layer**: Project management, task tracking, priority-based workflow (WHAT/WHEN)
- **Knowledge Layer**: RAG queries, web crawling, document processing, code examples
- **Integration Layer**: Connects Claude Code, Cursor, Windsurf with unified context

**The Two-Layer Architecture**:

- **Archon** (this skill) = Strategic (WHAT to build, WHEN)
- **Skills** = Tactical (HOW to build well)
- Together = Optimal outcomes

---

## When to Use This Skill

- **Project Setup**: Creating hierarchical projects with features and tasks
- **Task Management**: Priority-based workflow (P0/P1/P2), status tracking
- **Knowledge Queries**: RAG searches across documentation, code examples, PDFs
- **Strategic Planning**: Using Archon to decide WHAT to build next
- **Two-Layer Workflow**: Implementing Archon (strategic) + Skills (tactical) pattern
- **Context Preservation**: Maintaining project knowledge across sessions
- **AI Coordination**: Synchronizing multiple AI assistants on same project

---

## Core Concepts

### 1. The Two-Layer Architecture

```
┌──────────────────────────────────────────────────┐
│           ARCHON MCP SERVER                      │
│           (Strategic Layer)                      │
│                                                  │
│  • Project management & task tracking           │
│  • Priority-based workflow (P0/P1/P2)          │
│  • Knowledge queries (RAG)                      │
│  • Code example search                          │
│  • Progress tracking & metrics                  │
│  • Context preservation                         │
└─────────────────┬────────────────────────────────┘
                  │
                  │ invokes when needed
                  ↓
┌──────────────────────────────────────────────────┐
│      AI-DEV-STANDARDS SKILLS                     │
│      (Tactical Layer)                            │
│                                                  │
│  • Domain-specific expertise                    │
│  • Implementation patterns                      │
│  • Quality standards                            │
│  • Best practices                               │
└──────────────────────────────────────────────────┘
```

**Key Insight**: Archon manages WHAT to build and WHEN, Skills guide HOW to build it well.

### 2. Hierarchical Project Structure

```
Project
├── Feature 1
│   ├── Task 1.1 (P0)
│   ├── Task 1.2 (P1)
│   └── Task 1.3 (P2)
├── Feature 2
│   ├── Task 2.1 (P0)
│   └── Task 2.2 (P1)
└── Knowledge Base
    ├── Web pages
    ├── PDFs
    ├── Code examples
    └── Documentation
```

### 3. Priority-Based Workflow

- **P0 (Critical)**: Must have for core value prop, blocks everything
- **P1 (High Value)**: Important but can wait, high impact
- **P2 (Nice to Have)**: Enhancement, low priority

### 4. Knowledge Management

- **Web Crawling**: Automatic sitemap detection, intelligent scraping
- **Document Processing**: PDFs with intelligent chunking
- **Code Examples**: Extract from documentation
- **Semantic Search**: Vector-based RAG with embeddings
- **Source Organization**: Tags, categories, versions

---

## 6-Phase Archon Implementation

### Phase 1: Setup & Configuration

**Goal**: Install and configure Archon for your project

#### 1.1 Prerequisites

```bash
# Required
- Docker Desktop (running)
- Node.js 18+
- Supabase account (cloud: https://supabase.com or local)
- LLM API key (OpenAI, Gemini, or Ollama)
```

#### 1.2 Installation

```bash
# Clone Archon
git clone https://github.com/coleam00/Archon.git
cd Archon

# Create .env file
cp .env.example .env

# Edit .env with your credentials
SUPABASE_URL=your-supabase-url
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
OPENAI_API_KEY=your-openai-key  # or GEMINI_API_KEY, OLLAMA_URL

# Set up database (run SQL migrations in Supabase SQL Editor)
# See: database/migrations/

# Start Archon
docker compose up --build -d

# Verify running
# Frontend: http://localhost:3737
# API: http://localhost:8181
# MCP: http://localhost:8051
```

#### 1.3 Connect to AI Assistant

**For Claude Code** (.claude/mcp-settings.json):

```json
{
  "mcpServers": {
    "archon": {
      "command": "node",
      "args": ["/path/to/archon/mcp-server/dist/index.js"],
      "env": {
        "ARCHON_API_URL": "http://localhost:8181"
      }
    }
  }
}
```

**For Cursor/Windsurf**: Similar MCP configuration in settings

#### 1.4 Verify Connection

```typescript
// Test Archon connection
archon: list_projects()
// Should return empty list or existing projects
```

---

### Phase 2: Project Creation

**Goal**: Set up hierarchical project structure

#### 2.1 Create Project

```typescript
// Using Archon MCP tool
archon: create_project({
  name: 'My Application',
  description: 'Full-stack web application for task management',
  status: 'active',
  metadata: {
    tech_stack: ['Next.js', 'Supabase', 'TypeScript'],
    team_size: 1,
    target_launch: '2025-12-01'
  }
})

// Returns: { project_id: "uuid", name: "My Application", ... }
```

#### 2.2 Add Features

```typescript
// Create major features
archon: create_feature({
  project_id: 'uuid',
  name: 'User Authentication',
  description: 'Complete auth system with email/OAuth',
  priority: 'P0',
  estimated_effort: '2 days'
})

archon: create_feature({
  project_id: 'uuid',
  name: 'Task Management',
  description: 'CRUD operations for tasks',
  priority: 'P0',
  estimated_effort: '3 days'
})

archon: create_feature({
  project_id: 'uuid',
  name: 'Team Collaboration',
  description: 'Share tasks with team members',
  priority: 'P1',
  estimated_effort: '4 days'
})
```

#### 2.3 Break Down Features into Tasks

```typescript
// Use AI-assisted task generation
archon: generate_tasks({
  feature_id: 'auth-feature-uuid',
  instructions: 'Break down authentication into implementation tasks',
  use_ai: true
})

// Or create manually
archon: create_task({
  feature_id: 'auth-feature-uuid',
  title: 'Implement email/password signup',
  description: 'Create signup form, API endpoint, database schema',
  priority: 'P0',
  status: 'todo',
  estimated_hours: 4,
  skills_to_use: ['api-designer', 'security-engineer', 'frontend-builder']
})
```

---

### Phase 3: Knowledge Base Setup

**Goal**: Build comprehensive knowledge base for AI queries

#### 3.1 Add Web Documentation

```typescript
// Crawl entire documentation site
archon: crawl_website({
  url: 'https://nextjs.org/docs',
  max_depth: 3,
  follow_sitemap: true,
  tags: ['nextjs', 'documentation']
})

// Archon automatically:
// - Detects sitemap
// - Crawls pages
// - Extracts text
// - Chunks intelligently
// - Generates embeddings
// - Stores in vector database
```

#### 3.2 Add PDF Documents

```typescript
// Upload PDFs (design docs, specs, research papers)
archon: add_document({
  file_path: '/path/to/architecture-spec.pdf',
  type: 'pdf',
  tags: ['architecture', 'design'],
  project_id: 'uuid'
})

// Archon automatically:
// - Extracts text from PDF
// - Chunks by sections/pages
// - Generates embeddings
// - Indexes for search
```

#### 3.3 Add Code Examples

```typescript
// Extract code examples from repos or docs
archon: extract_code_examples({
  source_url: 'https://github.com/vercel/next.js/tree/canary/examples',
  tags: ['nextjs', 'examples'],
  language_filter: ['typescript', 'javascript']
})
```

#### 3.4 Organize Knowledge

```typescript
// Tag and categorize
archon: update_source({
  source_id: 'uuid',
  tags: ['authentication', 'security', 'best-practices'],
  category: 'implementation-guides',
  version: '1.0'
})
```

---

### Phase 4: The Archon+Skills Workflow

**Goal**: Use two-layer architecture for optimal development

#### 4.1 Phase 1: Strategic Planning (Archon)

**Goal**: Understand WHAT to build and WHY

```typescript
// 1. Get next priority task
const task = arc