Skip to content

creating-projects.md

Latest commit

 

History

History
323 lines (260 loc) · 13.4 KB

creating-projects.md

File metadata and controls

323 lines (260 loc) · 13.4 KB

What Happens When You Create a Project

Internal Systems Architecture Deep Dive

When a user says create_project("Build a web app for task management"), they trigger a sophisticated 7-stage orchestration involving 15+ interconnected systems. This document explains the internal complexity and system coordination that happens behind the scenes.

🎯 The Complete Flow Overview

User Request → NLP Processing → PRD Analysis → Task Generation → Dependency Inference → Board Creation → Learning Storage
     ↓              ↓              ↓              ↓                ↓                ↓              ↓
 [MCP Tool]    [AI Engine]   [PRD Parser]   [Task Intel]    [Context System]   [Kanban Integ]  [Memory Sys]

Result: A fully structured project with intelligent tasks, proper dependencies, and learning patterns stored for future projects.

📋 Stage 1: Entry Point & Validation

System: 34-create-project-tool.md (MCP Tool Layer)

What Happens:

  1. Parameter Validation: Ensures description isn't empty, project name is valid
  2. Pipeline Tracking: Generates unique flow ID for real-time monitoring
  3. State Initialization: Prepares project context and error recovery mechanisms
  4. Background Task Creation: Starts async tracking (creates MCP protocol challenges)

Data Created:

{
  "flow_id": "proj_2025_001_abc123",
  "timestamp": "2025-09-05T10:30:00Z",
  "status": "initiated",
  "tracking_active": true
}

🧠 Stage 2: Natural Language Processing

System: 38-natural-language-project-creation.md (NLP Pipeline)

What Happens:

  1. Context Detection: Analyzes current board state to determine creation mode
  2. Constraint Building: Maps user options (complexity, team size, tech stack) to internal constraints
  3. Mode Selection: Chooses between "add to existing board" vs "new project" processing

Intelligence Applied:

  • Project Complexity Classification: Prototype (8 tasks) vs Standard (20 tasks) vs Enterprise (50+ tasks)
  • Technology Stack Inference: Extracts tech requirements from natural language
  • Deadline Analysis: Interprets time constraints and urgency

📊 Stage 3: PRD Analysis & Decomposition

System: 38-natural-language-project-creation.md (Advanced PRD Parser)

What Is A PRD?

A Product Requirements Document is a formal specification that describes what a software product should do. Marcus treats every project description - even casual ones like "build a todo app" - as if it were a formal PRD that needs to be analyzed and structured.

What Happens:

Marcus sends your description to its AI engine with specialized prompts that extract seven key components:

1. Functional Requirements - What the system must DO

Examples from "build a task management web app":

  • "Users must be able to create, edit, and delete tasks"
  • "Users must be able to assign due dates to tasks"
  • "Users must be able to mark tasks as complete"
  • "System must display task lists organized by project"

2. Non-Functional Requirements (NFRs) - HOW WELL it must do it

Examples:

  • "Response time must be under 200ms for task operations"
  • "System must support 100 concurrent users"
  • "Data must be backed up daily"
  • "Interface must be mobile-responsive"

3. Technical Constraints - Technology and integration limitations

Examples:

  • "Must use React for frontend" (if specified)
  • "Must integrate with existing user authentication system"
  • "Must work offline for core functionality"
  • "Must deploy to AWS infrastructure"

4. Business Objectives - WHY this project exists

Examples:

  • "Improve team productivity by 25%"
  • "Reduce time spent on task coordination"
  • "Replace current inefficient spreadsheet-based tracking"

5. User Personas - WHO will use this

Examples:

  • "Project managers who need oversight of team progress"
  • "Individual contributors who need personal task tracking"
  • "Executives who need high-level project status"

6. Success Metrics - HOW to measure success

Examples:

  • "Task creation time reduced from 2 minutes to 30 seconds"
  • "95% user adoption within first month"
  • "Zero data loss incidents"

7. Implementation Approach - HIGH-LEVEL technical strategy

Examples:

  • "Single-page application with REST API backend"
  • "Microservices architecture with event-driven communication"
  • "Progressive web app with offline-first design"

The Five Critical Decisions:

Decision 1: Project Complexity Classification

if project_size in ["prototype", "mvp"]:
    max_tasks = 8           # Just core features
    include_infrastructure = False
elif project_size in ["standard", "medium"]:
    max_tasks = 20          # Balanced feature set
    include_infrastructure = True
else:  # enterprise
    max_tasks = 50+         # Comprehensive coverage
    include_infrastructure = True
    include_compliance = True

Decision 2: NFR Inclusion Strategy

Non-functional requirements add complexity, so Marcus decides which ones matter:

if project_size == "prototype":
    nfrs = nfrs[:1]  # Only the most critical NFR (usually security)
elif project_size == "standard":
    nfrs = nfrs[:3]  # Key performance and security requirements
else:  # enterprise
    nfrs = nfrs      # All NFRs including compliance, monitoring, etc.

Decision 3: Task Granularity

How detailed should tasks be?

  • Prototype: "Implement user authentication" (high-level)
  • Standard: "Set up OAuth2", "Create login UI", "Handle auth errors" (medium detail)
  • Enterprise: "Configure OAuth2 provider", "Design login form", "Implement form validation", "Add loading states", "Handle network errors", "Add accessibility features" (very detailed)

Decision 4: Dependency Complexity

How sophisticated should task relationships be?

  • Prototype: Simple linear dependencies (A → B → C)
  • Standard: Cross-functional dependencies (Frontend tasks can start once API design is done)
  • Enterprise: Complex dependency graphs with parallel tracks and integration points

Decision 5: Infrastructure Requirements

What supporting systems are needed?

if deployment_target == "none":
    # No deployment tasks, just development
elif deployment_target == "internal":
    # Basic CI/CD, staging environment
elif deployment_target == "production":
    # Full deployment pipeline, monitoring, scaling, backup systems

Data Generated:

PRDAnalysis {
    functional_requirements: [
        {"id": "F001", "description": "User authentication", "priority": "HIGH"},
        {"id": "F002", "description": "Task CRUD operations", "priority": "HIGH"},
        {"id": "F003", "description": "Project organization", "priority": "MEDIUM"}
    ],
    non_functional_requirements: [
        {"id": "NFR001", "description": "<1s response time", "category": "performance"},
        {"id": "NFR002", "description": "Mobile responsive", "category": "usability"}
    ],
    technical_constraints: ["React frontend", "Python backend", "PostgreSQL database"],
    business_objectives: ["Improve team productivity", "Replace spreadsheet workflow"],
    complexity_assessment: {"frontend": "medium", "backend": "high", "database": "low"},
    confidence: 0.85  # How confident the AI is in this analysis
}

⚡ Stage 4: Intelligent Task Generation

System: 23-task-management-intelligence.md (Task Intelligence Engine)

What Happens:

  1. Template Engine: Selects appropriate task templates based on project type
  2. Phase Generation: Creates logical project phases (Planning → Development → Testing → Deployment)
  3. Task Creation: Generates specific, actionable tasks from requirements
  4. Dependency Building: Establishes prerequisite relationships between tasks

Intelligence Applied:

  • Pattern Matching: Uses learned patterns from previous similar projects
  • Complexity Adjustment: Adjusts task granularity based on project complexity
  • Safety Validation: Prevents illogical dependencies (e.g., "Deploy" before "Develop")

Task Structure Created:

Task {
    id: "task_001"
    name: "Set up React development environment"
    description: "Configure build tools, linting, testing framework"
    status: "TODO"
    priority: "HIGH"
    estimated_hours: 2.0
    dependencies: []  # First task, no dependencies
    labels: ["setup", "frontend"]
    phase: "planning"
}

🔗 Stage 5: Dependency Inference & Validation

System: 03-context-dependency-system.md (Hybrid Dependency Engine)

What Happens:

  1. Pattern Rules: Applies logical dependency rules (setup before development)
  2. AI Analysis: Uses AI to infer complex dependencies between tasks
  3. Automatic Issue Correction: Via the Task Graph Auto-Fix System, automatically fixes:
    • Orphaned dependencies (references to non-existent tasks)
    • Circular dependencies (removes back-edges to break cycles)
    • Missing final task dependencies (ensures PROJECT_SUCCESS runs last)
  4. Cycle Detection: Ensures dependency graph is acyclic after fixes

Intelligence Applied:

  • Learning from Memory: 01-memory-system.md provides patterns from past projects
  • Context Awareness: Understands how tasks in this project relate to each other
  • Risk Mitigation: Identifies dependency risks and suggests alternatives
  • Silent Correction: Issues are fixed automatically without failing the creation process

Dependency Graph Created:

Setup Tasks → Core Development → Feature Development → Testing → Deployment
    ↓               ↓                    ↓             ↓          ↓
[task_001]    [task_005-010]       [task_011-015]  [task_016]  [task_017]

📋 Stage 6: Board Creation & Integration

System: 04-kanban-integration.md (Multi-Provider Kanban)

What Happens:

  1. Provider Selection: Chooses appropriate Kanban provider (Planka, Linear, GitHub)
  2. Board Structure: Creates board with proper columns (TODO, In Progress, Done, Blocked)
  3. Task Creation: Generates tasks on the board with all metadata
  4. Metadata Enrichment: Adds labels, priorities, time estimates, dependencies

Data Persistence:

  • Board State: 16-project-management.md tracks project in registry
  • Task Assignments: 35-assignment-lease-system.md prepares for agent requests
  • Project Context: 03-context-dependency-system.md maintains project state

🧠 Stage 7: Learning & Memory Storage

System: 01-memory-system.md (Multi-Tier Memory)

What Happens:

  1. Episodic Memory: Records this project creation event with all context
  2. Semantic Memory: Updates patterns about project types and task structures
  3. Procedural Memory: Reinforces successful project breakdown approaches
  4. Working Memory: Maintains current project state for immediate access

Learning Patterns Stored:

ProjectPattern {
    project_type: "web_app_task_management"
    typical_tasks: ["auth", "crud", "dashboard", "deployment"]
    typical_dependencies: {"auth": [], "crud": ["auth"], "dashboard": ["crud"]}
    success_factors: ["clear requirements", "iterative development"]
    risk_factors: ["scope creep", "technology complexity"]
    time_estimates: {"auth": 4h, "crud": 8h, "dashboard": 12h}
}

💾 Data Persistence Across Systems

What Gets Stored Where:

data/marcus_state/projects.json     ← Project registry and metadata
data/assignments/                   ← Task assignment tracking
data/marcus_state/memory/          ← Learning patterns and outcomes
data/audit_logs/                   ← Complete audit trail of creation
data/token_usage.json             ← AI API costs for this project

System State Changes:

  • Event System: 09-event-driven-architecture.md broadcasts project creation events
  • Service Registry: 15-service-registry.md updates available project services
  • Monitoring: 11-monitoring-systems.md begins tracking project health
  • Configuration: 28-configuration-management.md applies project-specific settings

🔄 Why This Complexity Matters

Without This Orchestration:

Users would need to manually:

  • Break down projects into tasks
  • Figure out dependencies
  • Estimate time requirements
  • Create board structure
  • Set up monitoring and tracking

With Marcus:

  • Intelligent Breakdown: AI-powered task generation with learned patterns
  • Dependency Intelligence: Automatic dependency inference with conflict resolution
  • Learning System: Gets better at project breakdown over time
  • Full Coordination: All systems work together seamlessly

The Result:

A single create_project() call produces a fully coordinated, dependency-aware, intelligently structured project ready for agent execution—with all supporting systems (monitoring, persistence, learning) automatically configured.

🎯 Key Takeaway

Project creation isn't just "make some tasks"—it's a sophisticated AI-powered analysis and coordination process that involves natural language understanding, intelligent task decomposition, dependency inference, multi-system coordination, and machine learning—all working together to transform a simple description into a fully orchestrated project ecosystem.

This is why Marcus can coordinate complex multi-agent work effectively: the intelligence is built into the project structure from the very beginning.