Archon Manager

Archon Manager

戦略的なプロジェクト管理とナレッジ運用のための Archon MCP。

Archon は AI コーディングアシスタントのコマンドセンターであり、次の機能を提供します。

• 戦略レイヤー：プロジェクト管理、タスク追跡、優先度ベースのワークフロー（WHAT／WHEN）
• ナレッジレイヤー：RAG クエリ、ウェブクロール、ドキュメント処理、コード例
• 統合レイヤー：Claude Code、Cursor、Windsurf を統一されたコンテキストで接続

2 層アーキテクチャ：

• Archon（このスキル）＝戦略（何を、いつ構築するか）
• スキル＝戦術（どのように適切に構築するか）
• 両者を組み合わせることで、最適な成果が得られます

---

このスキルを使用する場面

• プロジェクトのセットアップ：機能とタスクを含む階層型プロジェクトの作成
• タスク管理：優先度ベースのワークフロー（P0／P1／P2）、ステータス追跡
• ナレッジクエリ：ドキュメント、コード例、PDF を横断した RAG 検索
• 戦略的な計画：Archon を使って次に何を構築するかを決定
• 2 層ワークフロー：Archon（戦略）＋スキル（戦術）のパターンを実装
• コンテキストの保持：セッションをまたいでプロジェクトの知識を維持
• AI の連携：同じプロジェクトで複数の AI アシスタントを同期

---

基本概念

1. 2 層アーキテクチャ

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

重要なポイント：Archon は何をいつ構築するかを管理し、スキルはそれを適切に構築する方法をガイドします。

2. 階層型プロジェクト構造

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. 優先度ベースのワークフロー

• P0（重大）：中核となる価値提案に必須で、すべての作業を妨げるもの
• P1（高価値）：重要ですが、後回しにできる影響の大きいもの
• P2（あると便利）：機能強化、優先度は低いもの

4. ナレッジ管理

• ウェブクロール：サイトマップの自動検出、インテリジェントなスクレイピング
• ドキュメント処理：インテリジェントなチャンク分割による PDF の処理
• コード例：ドキュメントから抽出
• セマンティック検索：埋め込み表現を用いたベクトルベースの RAG
• ソースの整理：タグ、カテゴリ、バージョン

---

Archon の 6 段階の実装

フェーズ 1：セットアップと設定

目標：プロジェクト用に Archon をインストールして設定します

1.1 前提条件

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

1.2 インストール

# 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 AI アシスタントへの接続

Claude Code の場合（.claude/mcp-settings.json）：

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

Cursor／Windsurf の場合：設定で同様の MCP 設定を行います

1.4 接続の確認

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

---

フェーズ 2：プロジェクトの作成

目標：階層型のプロジェクト構造をセットアップします

2.1 プロジェクトの作成

// 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 機能の追加

// 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 機能をタスクに分解

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

---

フェーズ 3：ナレッジベースのセットアップ

目標：AI クエリ用の包括的なナレッジベースを構築します

3.1 ウェブドキュメントの追加

// 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 PDF ドキュメントの追加

// 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 コード例の追加

// 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 ナレッジの整理

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

---

フェーズ 4：Archon＋スキルのワークフロー

目標：最適な開発のために 2 層アーキテクチャを使用します

4.1 フェーズ 1：戦略的な計画（Archon）

目標：何を構築するか、そしてその理由を理解します

// 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 フェーズ 2：戦術的な実行（スキル）

目標：専門知識とベストプラクティスを活かして実装します

// 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 フェーズ 3：品質の検証

目標：完了とする前に品質を確認します

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

---

フェーズ 5：高度なナレッジ運用

目標：Archon の RAG 機能を活用します

5.1 セマンティック検索のパターン

// 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 コンテキストを考慮したクエリ

// 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 ナレッジベースのバージョン管理

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

---

フェーズ 6：進捗の追跡と指標

目標：プロジェクトの健全性と進捗速度を監視します

6.1 プロジェクト指標

// 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 進捗速度の追跡

// 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 リアルタイム更新

Archon は Socket.IO を使用して、進捗をリアルタイムで更新します。

• タスクステータスの変更
• ナレッジベースへの追加
• プロジェクト指標の更新
• チームコラボレーションのイベント

---

統合パターン

パターン 1：個人開発者のワークフロー

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

パターン 2：チームコラボレーション

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

パターン 3：複数の AI アシスタントのセットアップ

// 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 ツールのリファレンス

プロジェクト管理

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

ナレッジ管理

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

メトリクスと分析

archon: get_project_metrics({ project_id })
archon: get_velocity({ project_id, time_period })
archon: get_burndown({ project_id, sprint_id })

---

ベストプラクティス

1. 明確なプロジェクト構成から始める

// 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. 優先度を効果的に活用する

P0（重大）：MVP に必須で、すべてを妨げるもの

• 中核となる価値提案機能
• 重大なバグ
• セキュリティの脆弱性

P1（高価値）：重要で、影響が大きいもの

• 大幅な機能強化
• 重要な最適化
• 主要な統合

P2（あると望ましい）：後回しにできるもの

• 磨き上げと改良
• 小規模な機能
• 重大ではない改善

3. 包括的なナレッジベースを構築する

// 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. RAG クエリを戦略的に活用する

// 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. タスクのステータス管理を徹底する

todo → doing → review → done

• todo：未着手
• doing：現在作業中（1～3 件に制限）
• review：検証の準備完了
• done：完了し、検証済み

変更時には、すぐにステータスを更新してください。

---

トラブルシューティング

問題：Archon に接続できない

症状：AI アシスタントで MCP ツールを利用できない

解決策：

1. Docker コンテナが実行中か確認します：docker ps
2. ポートがブロックされていないか確認します：3737、8181、8051、8052
3. .claude/mcp-settings.json の MCP 設定を確認します
4. 設定を変更した後、AI アシスタントを再起動します
5. Archon のログを確認します：docker logs archon-api

問題：RAG クエリで結果が返されない

症状：perform_rag_query から空の結果が返される

解決策：

1. ナレッジベースにコンテンツがあるか確認します：archon:list_sources()
2. 埋め込みが生成されているか確認します（処理が完了するまで待ちます）
3. similarity_threshold を下げます（デフォルトは 0.7 です。0.5 を試してください）
4. より広い範囲のクエリ用語を使用します
5. ソースタグが filter_tags と一致しているか確認します

問題：タスクが表示されない

症状：get_next_task が空の結果を返す

解決策：

1. プロジェクトが存在するか確認します：archon:list_projects()
2. タスクのステータスフィルターを確認します
3. 正しい機能／プロジェクトにタスクが作成されていることを確認します
4. すべてのタスクが「done」とマークされていないか確認します

問題：パフォーマンスが遅い

症状：RAG クエリやタスク操作に時間がかかる

解決策：

1. Docker のリソース割り当てを確認します
2. ナレッジベースを最適化します（重複を削除します）
3. match_count を適切に使用します（100 ではなく 5～10）
4. Supabase プランのアップグレードを検討します（クラウドの場合）
5. API 呼び出しの代わりにローカルの Ollama を使用します

---

ai-dev-standards との統合

Archon とスキルの併用

Archon が提供するもの（戦略）：

• 何を構築するか（優先度キュー内のタスク）
• いつ構築するか（P0／P1／P2 の順序）
• コンテキスト（RAG クエリ、プロジェクトの知識）

スキルが提供するもの（戦術）：

• どのように適切に構築するか（ベストプラクティス、パターン）
• ドメインの専門知識（セキュリティ、パフォーマンスなど）
• 品質基準（テスト、検証）

ワークフローの例：

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

タスクとスキルの対応付け

Archon でタスクを作成する際、skills_to_use を指定します：

archon: create_task({
  title: 'Implement authentication API',
  skills_to_use: ['api-designer', 'security-engineer']
  // ...
})

これにより、実装中にどのスキルを呼び出すかを AI アシスタントに伝えます。

---

成功指標

次の状態であれば、Archon を効果的に活用できています：

1. ✅ 明確なプロジェクト構成：階層的に整理され、優先順位が付けられている
2. ✅ 次に何をすべきか常に把握できる：get_next_task が日々の作業を導く
3. ✅ 充実したナレッジベース：RAG クエリから関連性が高く有用な結果が返される
4. ✅ 進捗が可視化されている：メトリクスで着実な完了状況が示される
5. ✅ ステータス管理が徹底されている：ワークフローに沿ってタスクが円滑に進む
6. ✅ コンテキストが保持される：中断後も情報を失わずにプロジェクトを再開できる
7. ✅ 品質が維持されている：2 層のワークフロー（Archon + スキル）によって優れた成果が生み出される

---

クイックリファレンス

よく使うコマンド

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

優先度のガイドライン

• P0：中核機能、重大なバグ、セキュリティ上の問題
• P1：重要な機能強化、最適化、統合
• P2：磨き上げ、小規模な機能、あると望ましい機能

ステータスの流れ

todo → doing (working) → review (validate) → done (complete)

---

概要

Archon は、以下を実現する戦略的な司令塔です。

• 何をいつ構築するかを管理します（優先順位キュー）。
• RAG（ナレッジベース）を通じてコンテキストを提供します。
• 進捗とメトリクスを追跡します。
• AI アシスタントを調整します。

Skills（優れた構築方法）と組み合わせることで、Archon は以下を実現します。

• 戦略的一貫性（すべての作業を目標に沿って進めます）。
• 戦術的な卓越性（分野の専門知識とベストプラクティス）。
• コンテキストの保持（知識を失いません）。
• 品質保証（多層的な検証）。

重要なポイント：戦略的な計画（何を／いつ）には Archon を使用し、実装のガイダンス（どのように）には Skills を呼び出してください。両者を組み合わせることで、最適な成果が得られます。

詳細な統合パターンについて：DOCS/ARCHON-INTEGRATION.md を参照してください。 完全な例について：EXAMPLES/archon-workflow-example.md を参照してください。