The Complete Agent-Marcus Interaction Flow#

0. User Project Board Setup#

Options:

  1. Ask Marcus to create a new project from your description - This will create a complete board with tasks

  2. Ask Marcus to list and select an existing board to work on or set this up in the config_marcus.json file

1. Agent Lifecycle & Core Loop#

STARTUP → REGISTER → [CONTINUOUS WORK LOOP] → NO TASKS AVAILABLE

The agent operates in a perpetual work cycle:

  1. Register once with Marcus (register_agent)

  2. Request task (request_next_task)

  3. Get context if needed (get_task_context)

  4. Work on task autonomously

  5. Report progress at 25%, 50%, 75% (report_task_progress)

  6. Log decisions as they’re made (log_decision)

  7. Create artifacts for other agents (log_artifact)

  8. Report completion at 100%

  9. Immediately request next task (loop continues)

2. Available Tools & Decision Criteria#

Agents have access to these Marcus tools:

Core Workflow Tools#

  • register_agent - Used ONCE at startup

  • request_next_task - Called IMMEDIATELY after any task completion

  • report_task_progress - Called at 25%, 50%, 75%, 100% milestones

  • report_blocker - When stuck and need AI-powered suggestions

Context & Information Tools#

  • get_task_context - Used when:

    • Task has listed dependencies

    • Task mentions “integrate”, “extend”, “based on”, “following”

    • Need to understand what was previously built

    • Want to check available artifacts

  • get_agent_status - Check own status and capabilities

Documentation Tools#

  • log_decision - Used IMMEDIATELY when making architectural choices:

    • Database selection

    • Framework choices

    • API design decisions

    • Naming conventions

    • Format: “I chose X because Y. This affects Z.”

  • log_artifact - Used when creating shareable documents:

    • API specifications → docs/api/

    • Design documents → docs/design/

    • Architecture decisions → docs/architecture/

    • Technical specs → docs/specifications/

    • Documentation → docs/

Project Creation#

  • create_project - Create new projects using natural language (NLP)

Note: check_task_dependencies is a human operator tool, not available to agents. Dependency information is delivered automatically inside the request_next_task response.

3. Context Flow & Decision Making#

When an agent receives a task, Marcus provides:

{
  "task": {
    "id": "task-123",
    "name": "Implement user API",
    "instructions": "Tiered instructions with context",
    "implementation_context": "Previous work from GitHub",
    "dependency_awareness": "3 tasks depend on your work:\n- Frontend (needs: REST endpoints)\n- Mobile (needs: JWT auth)",
    "full_context": {
      "previous_implementations": {...},
      "dependent_tasks": [...],
      "related_patterns": [...],
      "architectural_decisions": [...]
    },
    "predictions": {
      "success_probability": 0.85,
      "completion_time": {"expected_hours": 4.2},
      "blockage_analysis": {"overall_risk": 0.3}
    }
  }
}

4. Agent Decision Process#

The agent follows this decision tree:

Task Received
├── Has dependencies? → get_task_context()
│   ├── Read new artifacts
│   └── Skip known artifacts
├── Making architectural choice? → log_decision()
├── Creating shareable docs? → log_artifact()
├── Hit 25/50/75% milestone? → report_task_progress()
├── Blocked? → report_blocker()
│   └── Try AI suggestions
└── Complete? → report_task_progress(100)
    └── IMMEDIATELY → request_next_task()

5. Smart Artifact Management#

Agents interact with artifacts intelligently:

# Example flow when task has dependencies
1. get_task_context() returns:
   artifacts: [
     {filename: "user-api.yaml", location: "docs/api/user-api.yaml"},
     {filename: "auth-design.md", location: "docs/design/auth-design.md"}
   ]

2. Agent decides:
   - Read("docs/api/user-api.yaml")     # Haven't seen this
   - Skip auth-design.md                # Already know JWT with 24h expiry

3. Creates new artifacts:
   - log_artifact("user-impl.md", content, "documentation")
   - log_artifact("user-model.ts", model, "specification")

6. Critical Behaviors#

ALWAYS:#

  • Complete tasks before requesting new ones

  • Request next task IMMEDIATELY after completion

  • Log decisions AS they’re made, not after

  • Follow existing patterns from context

  • Report specific implementation details

NEVER:#

  • Wait for user permission

  • Skip tasks or leave incomplete

  • Ask for clarification

  • Coordinate directly with other agents

  • Stop the work loop

7. Integration with Marcus Systems#

The agent’s actions trigger Marcus’s internal systems:

  • Context System - Builds rich context from dependencies

  • Memory System - Predicts outcomes and learns from performance

  • Dependency System - Ensures logical task ordering

  • Event System - Broadcasts agent activities

  • Persistence System - Stores decisions and artifacts

8. How Marcus Establishes Context#

Marcus establishes context through a sophisticated multi-layered system:

Context Collection Sources#

Marcus gathers context from multiple sources:

  • Previous implementations from completed dependency tasks

  • Dependent tasks that will need the agent’s work

  • Architectural decisions made by other agents

  • Related patterns from similar tasks

  • GitHub code analysis (when using GitHub provider)

  • Kanban attachments and artifacts

Context Delivery Mechanism#

When an agent calls request_next_task, Marcus:

  1. Finds the optimal task for the agent

  2. Analyzes task dependencies (both explicit and inferred)

  3. Builds a TaskContext object containing:

    • Previous implementations from dependencies

    • Tasks that depend on this work

    • Related patterns and architectural decisions

    • Predictions about success probability and completion time

  4. Generates tiered instructions that include all context

Dependency Inference System#

Marcus uses three levels of dependency inference:

  • Pattern-based rules: Common patterns like “frontend depends on API”

  • AI-enhanced analysis: Using Claude to understand complex relationships

  • Adaptive learning: Learning from user feedback and project patterns

Context Delivery Format#

The context is delivered in the task assignment response as shown in Section 3 above. The system ensures agents have the full picture of what came before, what’s needed now, and what will depend on their work - enabling them to make informed implementation decisions without constant back-and-forth communication.

Summary#

The agent workflow is a carefully orchestrated system where agents operate autonomously in a continuous loop, making intelligent decisions about when to gather context, log decisions, create artifacts, and report progress - all while Marcus provides rich contextual information and predictions to guide their work.