Skip to main content

📊 Archon Projects: AI-Powered Project Management

Manage your development projects with AI assistance. Track tasks, organize documentation, and connect your entire workflow with Cursor, Windsurf, and other AI coding assistants.

Archon Projects brings intelligent project management to your AI development workflow. Your AI assistants can understand project context, create and update tasks, manage documentation, and help you stay organized while you code.

🎯 Overview​

The Archon task management system provides:

  • Project Organization: Structured project management with PRDs, features, and documentation
  • Task Organization: Organize and group related tasks
  • Status Tracking: Todo, Doing, Review, Done status management
  • MCP Integration: AI agents can create, update, and query tasks autonomously
  • Reference Management: Link tasks to code examples and documentation sources
  • GitHub Integration: Connect projects to repositories for context

🏗️ System Architecture​

📊 Data Structure​

Archon uses a simple but flexible data structure:

  • Projects: Main containers with title, description, PRD, features, and GitHub integration
  • Tasks: Organized under projects with logical grouping
  • Documents: JSONB-based document storage for PRDs, specs, and other project docs
  • Status Tracking: Simple workflow - Todo → Doing → Review → Done

🚀 Getting Started​

Creating Your First Project​

Via Web Interface​

  1. Open Archon: Navigate to http://localhost:3737
  2. Go to Projects: Click the "Projects" tab in the navigation
  3. Create Project: Click "New Project"
  4. Fill Details:
    • Title: "My Documentation Project"
    • Description: Brief project overview
    • GitHub Repo: (optional) Repository URL
  5. Save Project: Click "Create"

Via API​

curl -X POST "http://localhost:8080/api/projects" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Documentation Overhaul",
    "prd": {
      "overview": "Improve API documentation for better developer experience",
      "goals": [
        "Add comprehensive examples",
        "Improve navigation structure",
        "Add interactive API explorer"
      ],
      "success_criteria": [
        "Reduce support tickets by 30%",
        "Increase API adoption by 50%"
      ]
    },
    "github_repo": "https://github.com/company/api-docs"
  }'

Via MCP (AI Agent)​

AI agents can autonomously create projects:

User: "I need to start a new project to improve our API documentation"
AI: [Uses create_project MCP tool] 
    "I've created a new project 'API Documentation Improvement' with a comprehensive PRD..."

Creating Tasks​

Via Web Interface​

  1. Select Project: Choose your project from the project list
  2. Add Task: Click "New Task"
  3. Fill Details:
    • Title: Clear, actionable task name
    • Description: Detailed requirements
    • Status: Initial status (usually "todo")
    • Assignee: Choose from User, Archon, or AI IDE Agent
    • Sources: Add reference documentation
    • Code Examples: Add relevant code snippets
  4. Save Task: Click "Create"

Via API​

curl -X POST "http://localhost:8080/api/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Create authentication examples",
    "description": "Write comprehensive examples showing how to implement JWT authentication with our API, including token generation, validation, and error handling.",
    "assignee": "Archon",
    "sources": [
      {
        "name": "JWT.io Introduction",
        "url": "https://jwt.io/introduction/",
        "description": "Basic JWT concepts and structure"
      },
      {
        "name": "FastAPI Security",
        "url": "https://fastapi.tiangolo.com/tutorial/security/",
        "description": "FastAPI authentication patterns"
      }
    ],
    "code_examples": [
      {
        "language": "python",
        "description": "JWT token generation",
        "code": "import jwt\nfrom datetime import datetime, timedelta\n\ndef create_token(user_id: str) -> str:\n    payload = {\n        'user_id': user_id,\n        'exp': datetime.utcnow() + timedelta(hours=24)\n    }\n    return jwt.encode(payload, SECRET_KEY, algorithm='HS256')"
      }
    ],
    "status": "todo"
  }'

🔧 Task Management Features​

Task Organization​

Break down complex work into manageable tasks:

# Create main task
curl -X POST "http://localhost:8080/api/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Implement user authentication system",
    "description": "Complete authentication system with JWT tokens",
    "status": "todo"
  }'

# Create related tasks
curl -X POST "http://localhost:8080/api/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Design JWT token structure",
    "description": "Define token payload and expiration strategy",
    "status": "todo",
    "feature": "Authentication"
  }'

Status Management​

Update task status as work progresses:

# Update task status
curl -X PATCH "http://localhost:8080/api/tasks/task-uuid-here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "doing",
    "description": "Started implementing JWT token generation. Updated payload structure to include user roles and permissions."
  }'

Status Workflow​

Task Filtering and Queries​

Get Tasks by Status​

# Get all "doing" tasks
curl "http://localhost:8080/api/tasks?status=doing"

# Get all tasks for a project
curl "http://localhost:8080/api/tasks?project_id=550e8400-e29b-41d4-a716-446655440000"

# Get tasks by feature
curl "http://localhost:8080/api/tasks?project_id=550e8400-e29b-41d4-a716-446655440000&feature=Authentication"

Advanced Filtering​

# Get tasks by status with project filter
curl "http://localhost:8080/api/tasks?project_id=550e8400-e29b-41d4-a716-446655440000&status=review"

🤖 MCP Integration​

AI coding assistants can autonomously manage tasks through MCP tools:

Available MCP Tools (5 Consolidated Tools)​

Streamlined MCP Tools

Following MCP best practices, we've consolidated 22 individual tools into 5 flexible, action-based tools. This provides better performance, easier maintenance, and more intuitive usage for AI agents.

Consolidated Project & Task Tools​

ToolActionsDescriptionParameters
manage_projectcreate, list, get, deleteComplete project lifecycleaction, project_id, title, prd, github_repo
manage_taskcreate, list, get, update, delete, archiveAll task operationsaction, task_id, project_id, filter_by, filter_value, update_fields
manage_documentadd, list, get, update, deleteDocument management (Not yet implemented)action, project_id, doc_id, document_type, title, content, metadata
manage_versionscreate, list, get, restoreVersion control (Not yet implemented)action, project_id, field_name, version_number, content
get_project_features(query only)Retrieve featuresproject_id
Implementation Status

The manage_document and manage_versions tools are defined in the MCP module but require corresponding Server API endpoints to be implemented. Currently, these tools will return "not yet implemented" errors. The other tools (manage_project, manage_task, and get_project_features) are fully functional.

Action Patterns​

# Create a new project
result = await manage_project(
    action="create",
    title="AI Documentation System",
    prd={"overview": "Automated docs generation", "goals": ["Generate API docs", "Maintain accuracy"]},
    github_repo="https://github.com/user/ai-docs"
)

# List all projects
projects = await manage_project(action="list")

# Get specific project
project = await manage_project(
    action="get",
    project_id="550e8400-e29b-41d4-a716-446655440000"
)
Document Format Requirements

When using manage_document with add or update actions, the content field MUST follow the structured MCP format. The UI will automatically convert this to editable blocks. Do not use flat text or unstructured data.

AI-Driven Task Management Examples​

Scenario 1: Project Planning​

User Prompt:

I need to plan a new feature for user profile management. 
Create a project and break it down into tasks.

AI Actions:

  1. manage_project with action="create" - Creates "User Profile Management" project with comprehensive PRD
  2. perform_rag_query - Finds existing user management patterns in knowledge base
  3. manage_task with action="create" (multiple calls) - Creates structured task breakdown:
    • Design user profile schema
    • Implement profile CRUD endpoints
    • Add profile validation
    • Create profile UI components
    • Write integration tests
  4. Links relevant documentation in task sources

Scenario 2: Progress Tracking​

User Prompt:

I just finished implementing the user registration endpoint. 
Update my tasks and suggest what to work on next.

AI Actions:

  1. manage_task with action="list" and filter_by="project" - Gets current project tasks
  2. manage_task with filter_by="status" and filter_value="doing" - Finds active tasks
  3. manage_task with action="update" - Marks registration task as "done"
  4. manage_task with filter_by="status" and filter_value="todo" - Finds next tasks
  5. Provides recommendations for next priority tasks

Scenario 3: Code Review Integration​

User Prompt:

Review this authentication code and create tasks for any improvements needed:
[code snippet]

AI Actions:

  1. perform_rag_query - Finds coding standards and security patterns
  2. Analyzes code against documented best practices
  3. manage_task with action="create" - Creates improvement tasks:
    • Add input validation
    • Implement rate limiting
    • Add comprehensive error handling
    • Improve test coverage
  4. manage_document with action="add" - Documents findings
  5. Sets appropriate priorities and dependencies

📊 Project Management Patterns​

PRD (Product Requirements Document) Structure​

When creating projects, Archon automatically generates a structured PRD:

{
  "prd": {
    "overview": "Clear description of what we're building and why",
    "problem_statement": "What problem are we solving?",
    "goals": [
      "Specific, measurable objectives",
      "User experience improvements",
      "Technical achievements"
    ],
    "success_criteria": [
      "Quantifiable success metrics",
      "User satisfaction targets",
      "Performance benchmarks"
    ],
    "scope": {
      "in_scope": ["Features to include"],
      "out_of_scope": ["Features explicitly excluded"]
    },
    "technical_requirements": [
      "Performance requirements",
      "Security requirements",
      "Scalability requirements"
    ],
    "stakeholders": [
      {
        "name": "Product Manager",
        "role": "Requirements owner",
        "contact": "pm@company.com"
      }
    ]
  }
}

Document Management​

Projects can contain various types of documents:

  • PRD (Product Requirements Document): Project overview, goals, and technical requirements
  • Technical Specs: Detailed implementation plans and architecture
  • Feature Plans: Feature breakdowns and user stories
  • Meeting Notes: Team discussions and decisions

Documents are stored in a structured format that works well with AI agents while providing rich editing through the BlockNote editor.

Feature Tracking​

Track feature development progress:

{
  "features": [
    {
      "name": "User Authentication",
      "status": "done",
      "priority": "high",
      "effort_estimate": "5 days",
      "actual_effort": "4 days",
      "dependencies": [],
      "tasks": [
        "660e8400-e29b-41d4-a716-446655440001",
        "660e8400-e29b-41d4-a716-446655440002"
      ]
    },
    {
      "name": "User Profile Management",
      "status": "in_progress",
      "priority": "medium",
      "effort_estimate": "8 days",
      "dependencies": ["User Authentication"],
      "blockers": []
    }
  ]
}

🎨 Frontend Integration​

The React frontend (ProjectPage.tsx - 593 lines) provides intuitive task management interfaces:

Project Dashboard Features​

  • Project Overview: Title, description, GitHub integration
  • Task Summary: Status breakdown, progress indicators
  • Document Management: PRD viewer, document creation
  • Feature Tracking: Feature status and dependencies

Task Management Interface​

  • Task List: Filterable by status, searchable
  • Task Details: Full task information, sources, code examples
  • Status Updates: Drag-and-drop status changes
  • Task Grouping: Organize tasks by feature or category

Real-time Updates​

The frontend receives real-time updates via Socket.IO connections when:

  • Tasks are created or updated by AI agents
  • Project status changes
  • Documents are added or modified

📈 Progress Tracking​

Archon provides built-in progress tracking:

  • Project completion percentage based on completed tasks
  • Task velocity showing development pace over time
  • Status distribution showing work distribution across todo/doing/review/done
  • Real-time updates via Socket.IO when AI agents or users update tasks

🔍 Best Practices​

Task Writing Guidelines​

Good Task Examples​

✅ Good: "Implement JWT authentication middleware for FastAPI"

  • Specific technology mentioned
  • Clear deliverable
  • Actionable

✅ Good: "Write unit tests for user registration endpoint covering happy path and validation errors"

  • Specific scope
  • Clear acceptance criteria
  • Testable outcome

Poor Task Examples​

❌ Poor: "Fix authentication"

  • Too vague
  • No clear scope
  • Not actionable

❌ Poor: "Make the app better"

  • No specific deliverable
  • Subjective criteria
  • Not measurable

Project Organization​

Project: "User Management System"
├── Epic: "Authentication"
│   ├── Task: "Design JWT token structure"
│   ├── Task: "Implement login endpoint"
│   ├── Task: "Implement logout endpoint"
│   └── Task: "Add authentication middleware"
├── Epic: "User Profiles"
│   ├── Task: "Design user profile schema"
│   ├── Task: "Implement profile CRUD endpoints"
│   └── Task: "Add profile validation"
└── Epic: "Testing & Documentation"
    ├── Task: "Write integration tests"
    ├── Task: "Update API documentation"
    └── Task: "Create user guides"

Status Management Best Practices​

When to Use Each Status​

  • Todo: Task is ready to start, all dependencies met
  • Doing: Work is actively in progress
  • Blocked: Cannot proceed due to external dependencies
  • Done: Task is completed and verified

Status Transition Guidelines​

🚀 Integration Examples​

Cursor IDE Integration​

Example of AI-assisted task management in Cursor:

User: "I need to implement user authentication for our API"

AI Response:
I'll help you plan the authentication implementation. Let me create a project and break this down into manageable tasks.

[AI uses MCP tools to:]
1. manage_project(action="create") with authentication project details
2. perform_rag_query("FastAPI authentication JWT")
3. manage_task(action="create") for each implementation step
4. Link relevant documentation from knowledge base

I've created a project "User Authentication System" with the following tasks:

1. ✅ Design JWT token structure
   - Status: todo
   - Sources: FastAPI Security docs, JWT.io guide
   - Code examples: Token generation and validation

2. ✅ Implement authentication middleware
   - Status: todo  
   - Sources: FastAPI middleware documentation
   - Code examples: Dependency injection patterns

3. ✅ Create login/logout endpoints
   - Status: todo
   - Sources: FastAPI routing documentation
   - Code examples: Request/response models

4. ✅ Add password hashing
   - Status: todo
   - Sources: Security best practices
   - Code examples: bcrypt implementation

5. ✅ Write authentication tests
   - Status: todo
   - Sources: FastAPI testing guide
   - Code examples: Test fixtures and mocks

Would you like me to start with any specific task?

GitHub Integration​

Projects can be linked to GitHub repositories for context. Future versions will include bidirectional sync with GitHub issues and pull requests.

🔮 What's Next​

Upcoming features include time tracking, task templates, team collaboration, and enhanced GitHub integration.

Next Steps: