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.

On this page
Edit on GitHub
Show Source