daffy0208/ai-dev-standards/archon-manager

┌──────────────────────────────────────────────────┐
│           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                               │
└──────────────────────────────────────────────────┘

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

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

# 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

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

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

// 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", ... }

// 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'
})

// 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']
})

// 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

// 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

// 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']
})

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

// 1. Get next priority task
const task = archon:get_next_task({
  project_id: "uuid",
  filter_by: "status",
  filter_value: "todo",
  sort_by: "priority"  // P0 first
})
// → { id: "P0-3", title: "Implement User Authentication", priority: "P0" }
// 2. Get task details
const details = archon:get_task({
  task_id: "P0-3"
})
// → Complete task info: description, requirements, dependencies
// 3. Research the domain (RAG query)
const research = archon:perform_rag_query({
  query: "JWT authentication Next.js best practices",
  project_id: "uuid",
  match_count: 5
})
// → Top 5 most relevant knowledge base entries with context
// 4. Find code examples
const examples = archon:search_code_examples({
  query: "auth middleware Next.js TypeScript",
  match_count: 3
})
// → Relevant code examples from knowledge base
// 5. Mark as doing
archon:update_task({
  task_id: "P0-3",
  updates: { status: "doing" }
})

// 6. Identify required skills (from task.skills_to_use)
// → ["api-designer", "security-engineer", "frontend-builder"]
// 7. Invoke skills for guidance
// (AI assistant automatically invokes these skills based on context)
// 8. Implement following both:
//    - Archon research (RAG results + code examples)
//    - Skill guidance (best practices + patterns)
// 9. Build the feature

// 10. Apply quality checks
// - Invoke testing-strategist skill
// - Invoke security-engineer skill
// - Run tests, validate security
// 11. Update task to review
archon:update_task({
  task_id: "P0-3",
  updates: { status: "review" }
})
// 12. After user validation → mark done
archon:update_task({
  task_id: "P0-3",
  updates: { status: "done" }
})
// 13. Get next task
const nextTask = archon:get_next_task({
  project_id: "uuid",
  filter_by: "status",
  filter_value: "todo"
})
// → Repeat cycle

// Broad research query
archon: perform_rag_query({
  query: 'How to implement real-time features in Next.js',
  match_count: 10,
  similarity_threshold: 0.7
})
// Specific technical query
archon: perform_rag_query({
  query: 'Next.js middleware authentication example code',
  match_count: 3,
  filter_tags: ['nextjs', 'authentication', 'code-example']
})
// Architecture decision query
archon: perform_rag_query({
  query: 'PostgreSQL vs MongoDB for user data',
  match_count: 5,
  filter_tags: ['database', 'architecture']
})

// Query within project context
archon: perform_rag_query({
  query: 'How should we structure our authentication?',
  project_id: 'uuid', // Uses project's knowledge base
  match_count: 5
})
// Query specific feature context
archon: perform_rag_query({
  query: 'Best practices for this feature',
  feature_id: 'auth-feature-uuid',
  match_count: 3
})

// Version project documentation
archon: create_doc_version({
  project_id: 'uuid',
  document_name: 'Architecture Decision Record',
  content: '...',
  version: '1.0.0',
  tags: ['architecture', 'decisions']
})
// Query historical context
archon: get_doc_history({
  project_id: 'uuid',
  document_name: 'Architecture Decision Record'
})

// Get project overview
archon: get_project_metrics({
  project_id: 'uuid'
})
// Returns:
// {
//   total_features: 5,
//   total_tasks: 23,
//   p0_tasks: 8,
//   p1_tasks: 10,
//   p2_tasks: 5,
//   tasks_by_status: {
//     todo: 15,
//     doing: 3,
//     review: 2,
//     done: 3
//   },
//   completion_percentage: 13,
//   knowledge_base_entries: 147
// }