Archon Manager: Скилл для управления проектами и задачами

--- name: Archon Manager description: Master Archon MCP for strategic project management, task tracking, and knowledge base operations. The strategic layer (WHAT/WHEN) that coordinates with Skills (HOW). Use when managing projects, tracking tasks, querying knowledge bases, or implementing the Archon+Skills two-layer architecture. version: 1.0.0 category: project-management tags: - project-management - knowledge-management - task-tracking - rag - strategic-planning related_skills: - rag-implementer - knowledge-base-manager - mvp-builder - product-strategist - multi-agent-architect triggers: - archon-manager - archon manager - archon - project management mcp - task tracking supports_mcps: - archon-mcp required_tools: [] required_integrations: - supabase - openai --- # 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 = 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" } }) ``` #### 4.2 Phase 2: Tactical Execution (Skills) **Goal**: Implement with domain expertise and best practices ```typescript // 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 ``` #### 4.3 Phase 3: Quality Validation **Goal**: Ensure quality before marking complete ```typescript // 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 ``` --- ### Phase 5: Advanced Knowledge Operations **Goal**: Leverage Archon's RAG capabilities #### 5.1 Semantic Search Patterns ```typescript // 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'] }) ``` #### 5.2 Context-Aware Queries ```typescript // 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 }) ``` #### 5.3 Knowledge Base Versioning ```typescript // 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' }) ``` --- ### Phase 6: Progress Tracking & Metrics **Goal**: Monitor project health and velocity #### 6.1 Project Metrics ```typescript // 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 // } ``` #### 6.2 Velocity Tracking ```typescript // Tasks completed per week archon: get_velocity({ project_id: 'uuid', time_period: 'week' }) // Burndown chart data archon: get_burndown({ project_id: 'uuid', sprint_id: 'sprint-1' }) ``` #### 6.3 Real-Time Updates Archon uses Socket.IO for real-time progress updates: - Task status changes - Knowledge base additions - Project metrics updates - Team collaboration events --- ## Integration Patterns ### Pattern 1: Solo Developer Workflow ```typescript // Morning routine const nextTask = archon:get_next_task({ project_id: "uuid" }) const research = archon:perform_rag_query({ query: nextTask.title + " implementation", match_count: 5 }) // Work on task (using Skills for implementation) // ... // End of day archon:update_task({ task_id: nextTask.id, status: "review" }) ``` ### Pattern 2: Team Collaboration ```typescript // Team lead creates project structure archon: create_project({ name: 'Team Project' }) archon: create_feature({ name: 'Backend API', assigned_to: 'developer-1' }) archon: create_feature({ name: 'Frontend UI', assigned_to: 'developer-2' }) // Each team member queries same knowledge base archon: perform_rag_query({ query: '...', project_id: 'uuid' }) // Real-time sync of task status across team ``` ### Pattern 3: Multi-AI-Assistant Setup ```typescript // Claude Code for implementation // Cursor for refactoring // Windsurf for testing // All connected to same Archon instance // Same project, same tasks, same knowledge base // Coordinated through Archon's unified context ``` --- ## Archon MCP Tools Reference ### Project Management ```typescript // Projects archon: create_project({ name, description, status, metadata }) archon: list_projects() archon: get_project({ project_id }) archon: update_project({ project_id, updates }) archon: delete_project({ project_id }) // Features archon: create_feature({ project_id, name, description, priority }) archon: list_features({ project_id }) archon: update_feature({ feature_id, updates }) // Tasks archon: create_task({ feature_id, title, description, priority, status }) archon: get_next_task({ project_id, filter_by, sort_by }) archon: get_task({ task_id }) archon: update_task({ task_id, updates }) archon: list_tasks({ project_id, filter_by, filter_value }) archon: generate_tasks({ feature_id, instructions, use_ai }) ``` ### Knowledge Management ```typescript // RAG Queries archon:perform_rag_query({query, project_id?, match_count, similarity_threshold, filter_tags?}) archon:search_code_examples({query, match_count, language_filter?}) // Content Ingestion archon:crawl_website({url, max_depth, follow_sitemap, tags}) archon:add_document({file_path, type, tags, project_id}) archon:extract_code_examples({source_url, tags, language_filter}) // Knowledge Base Management archon:list_sources({project_id, filter_tags?}) archon:update_source({source_id, tags, category, version}) archon:delete_source({source_id}) ``` ### Metrics & Analytics ```typescript archon: get_project_metrics({ project_id }) archon: get_velocity({ project_id, time_period }) archon: get_burndown({ project_id, sprint_id }) ``` --- ## Best Practices ### 1. Start with Clear Project Structure ```typescript // Good: Hierarchical and organized Project: "E-commerce Platform" ├── Feature: "User Authentication" (P0) │ ├── Task: "Implement signup" (P0) │ ├── Task: "Implement login" (P0) │ └── Task: "Password reset" (P1) ├── Feature: "Product Catalog" (P0) │ ├── Task: "Product CRUD API" (P0) │ ├── Task: "Product listing UI" (P0) │ └── Task: "Search functionality" (P1) // Bad: Flat, disorganized - Task: "Build everything" - Task: "Make it work" - Task: "Deploy" ``` ### 2. Use Priority Effectively **P0 (Critical)**: Must have for MVP, blocks everything - Core value proposition features - Critical bugs - Security vulnerabilities **P1 (High Value)**: Important, high impact - Significant enhancements - Important optimizations - Major integrations **P2 (Nice to Have)**: Can wait - Polish and refinement - Minor features - Non-critical improvements ### 3. Build Comprehensive Knowledge Base ```typescript // Add diverse sources archon: crawl_website({ url: 'https://docs.framework.com' }) archon: add_document({ file_path: 'architecture-spec.pdf' }) archon: extract_code_examples({ source_url: 'https://github.com/...' }) // Tag consistently tags: ['category', 'technology', 'type'] // e.g., ["authentication", "nextjs", "tutorial"] ``` ### 4. Use RAG Queries Strategically ```typescript // Before starting task const research = archon:perform_rag_query({ query: "How to implement " + task.title, match_count: 5 }) // During implementation (specific questions) const answer = archon:perform_rag_query({ query: "How to handle edge case X", match_count: 3 }) // Architecture decisions const guidance = archon:perform_rag_query({ query: "Should I use pattern A or pattern B for ...", match_count: 5 }) ``` ### 5. Maintain Task Status Discipline ``` todo → doing → review → done ``` - **todo**: Not started - **doing**: Currently working on (limit to 1-3 tasks) - **review**: Ready for validation - **done**: Completed and validated Update status immediately when changing. --- ## Troubleshooting ### Issue: Archon Not Connecting **Symptoms**: MCP tools not available in AI assistant **Solutions**: 1. Check Docker containers running: `docker ps` 2. Verify ports not blocked: 3737, 8181, 8051, 8052 3. Check MCP configuration in `.claude/mcp-settings.json` 4. Restart AI assistant after config changes 5. Check Archon logs: `docker logs archon-api` ### Issue: RAG Queries Return No Results **Symptoms**: Empty results from `perform_rag_query` **Solutions**: 1. Verify knowledge base has content: `archon:list_sources()` 2. Check embeddings generated (wait for processing) 3. Lower `similarity_threshold` (default 0.7, try 0.5) 4. Broader query terms 5. Check source tags match `filter_tags` ### Issue: Tasks Not Appearing **Symptoms**: `get_next_task` returns empty **Solutions**: 1. Verify project exists: `archon:list_projects()` 2. Check task status filters 3. Ensure tasks created for correct feature/project 4. Verify tasks not all marked "done" ### Issue: Slow Performance **Symptoms**: RAG queries or task operations slow **Solutions**: 1. Check Docker resource allocation 2. Optimize knowledge base (remove duplicates) 3. Use `match_count` appropriately (5-10, not 100) 4. Consider upgrading Supabase plan (if cloud) 5. Use local Ollama instead of API calls --- ## Integration with ai-dev-standards ### Using Archon + Skills Together **Archon provides** (Strategic): - WHAT to build (task from priority queue) - WHEN to build it (P0/P1/P2 ordering) - Context (RAG queries, project knowledge) **Skills provide** (Tactical): - HOW to build well (best practices, patterns) - Domain expertise (security, performance, etc.) - Quality standards (testing, validation) **Example Workflow**: ```typescript // 1. Strategic (Archon) const task = archon:get_next_task({project_id: "uuid"}) const research = archon:perform_rag_query({query: task.title}) archon:update_task({task_id: task.id, status: "doing"}) // 2. Tactical (Skills) // AI automatically invokes: api-designer, security-engineer, frontend-builder // Based on task.skills_to_use // 3. Implementation // Build following: Archon research + Skill guidance // 4. Quality (Skills) // AI invokes: testing-strategist, security-engineer // 5. Complete (Archon) archon:update_task({task_id: task.id, status: "done"}) ``` ### Task-to-Skill Mapping When creating tasks in Archon, specify `skills_to_use`: ```typescript archon: create_task({ title: 'Implement authentication API', skills_to_use: ['api-designer', 'security-engineer'] // ... }) ``` This tells AI assistants which skills to invoke during implementation. --- ## Success Metrics You're using Archon effectively when: 1. ✅ **Clear project structure**: Hierarchical, organized, prioritized 2. ✅ **Always know what's next**: `get_next_task` guides daily work 3. ✅ **Rich knowledge base**: RAG queries return relevant, useful results 4. ✅ **Visible progress**: Metrics show steady completion 5. ✅ **Status discipline**: Tasks flow smoothly through workflow 6. ✅ **Context preserved**: Can resume project after breaks without loss 7. ✅ **Quality maintained**: Two-layer workflow (Archon + Skills) produces excellent results --- ## Quick Reference ### Common Commands ```typescript // Daily workflow archon: get_next_task({ project_id }) archon: perform_rag_query({ query, match_count: 5 }) archon: update_task({ task_id, status: 'doing' }) // ... work ... archon: update_task({ task_id, status: 'done' }) // Project setup archon: create_project({ name, description }) archon: create_feature({ project_id, name, priority: 'P0' }) archon: create_task({ feature_id, title, priority: 'P0' }) // Knowledge building archon: crawl_website({ url, tags }) archon: add_document({ file_path, tags }) // Progress tracking archon: get_project_metrics({ project_id }) archon: list_tasks({ project_id, filter_by: 'status', filter_value: 'done' }) ``` ### Priority Guidelines - **P0**: Core features, critical bugs, security issues - **P1**: Important enhancements, optimizations, integrations - **P2**: Polish, minor features, nice-to-haves ### Status Flow ``` todo → doing (working) → review (validate) → done (complete) ``` --- ## Summary Archon is the strategic command center that: - Manages WHAT to build and WHEN (priority queue) - Provides context through RAG (knowledge base) - Tracks progress and metrics - Coordinates AI assistants Combined with Skills (HOW to build well), Archon enables: - Strategic coherence (all work aligned with goals) - Tactical excellence (domain expertise + best practices) - Context preservation (no lost knowledge) - Quality assurance (multi-layer validation) **Key Takeaway**: Use Archon for strategic planning (WHAT/WHEN), invoke Skills for implementation guidance (HOW). Together they create optimal outcomes. **For detailed integration patterns**: See `DOCS/ARCHON-INTEGRATION.md` **For complete example**: See `EXAMPLES/archon-workflow-example.md`