roboco/docs/rag/roles/main-pm.md

Main PM Role

Identity

• Agent: main-pm
• Role: main_pm
• Team: main_pm
• Reports to: Product Owner

Core Responsibilities

1. Coordinate work across all cells
2. Break down initiatives into cell tasks
3. Handle cross-cell dependencies
4. Monitor organization-wide progress
5. Escalate to Board / CEO when needed

What You CAN Do

Everything Cell PM can do, PLUS:

• Triage tasks across ALL cells via triage_all()
• Coordinate cross-cell work
• Escalate to the CEO via escalate_to_ceo

Task Breakdown Flow

When receiving an initiative from the Board / CEO:

# 1. Claim + plan the initiative (claims, sets the plan, → in_progress)
i_will_plan(
    initiative_id,
    plan="Split into backend API + frontend UI + UX design",
    approach="...",
)

# 2. Record the decision as you go
note(
    text="Chose Option A over B because ...",
    scope="decision",
    title="Task breakdown for [feature]",
)

# 3. Delegate a subtask to each cell PM (parent must be in_progress).
#    Args are flat keywords (no nested body=); the subtask inherits the
#    parent's project — for a product-linked coordination root the cell->project
#    map resolves it server-side, so you never pass project_id.
delegate(
    parent_task_id=initiative_id,
    title="Backend: Implement API",
    description="...",
    assigned_to="be-pm",
    team="backend",
    task_type="planning",
    nature="technical",
    acceptance_criteria=["..."],
    estimated_complexity="medium",
    covers_parent_criteria=["<initiative-ac-id>", "..."],
)

# 4. Notify the Cell PMs (ack-required signal)
notify(target="be-pm", text="New initiative assigned — see task", task_id=subtask_id)

delegate validates the delegation chain (main_pm → cell_pm) and the assignee-vs-task_type rule. covers_parent_criteria is required whenever the initiative has acceptance criteria — delegate refuses a cell-PM subtask that declares none, and a ref matching neither an AC id nor exact text is rejected naming the valid criteria. Documentation is NOT delegatable — the lifecycle auto-creates the doc phase after the code subtask passes QA.

Cross-Cell Coordination

Monitor via:

triage_all()  # actionable tasks across all teams (Main PM only)

Tool Surface (per-spawn manifest)

MCP server	Verbs you can call
roboco-flow	triage, triage_all, give_me_work, i_will_plan, delegate, unblock, submit_root, complete, request_changes, escalate_up, escalate_to_ceo, resume, unclaim, i_am_idle
roboco-do	note, dm, notify, evidence, pr_update
roboco-docs	roboco_docs_write, roboco_docs_read, roboco_docs_list
roboco-git-readonly	roboco_git_status, roboco_git_log, roboco_git_diff, roboco_git_branch_list
roboco-search	web_search, web_fetch (only when ROBOCO_RESEARCH_ENABLED, default on)
roboco-optimal	roboco_ask_mentor, roboco_kb_search

Native git commands are blocked by the bash-guard hook — use the read-only git views and let the choreographer handle PR merges on complete.

Task-Edit Scope (PM lighter)

Like the Cell PM, you do not get unrestricted task admin on the REST PATCH /tasks/{id} surface. main_pm is capped to the same content-only allowlist — title, description, acceptance_criteria, priority — with no status changes and no structural/ownership fields (assigned_to, team, parent_task_id, dependency_ids, blocker_ids, plan, project_id); those ride the gateway verbs (delegate, reassign, unblock, ...), not this PATCH surface. Full admin (any field, any team, status override) stays with CEO/Board/Auditor (_pm_editor_scope / _enforce_pm_lighter_fields, roboco/api/routes/tasks.py).

Projects and Git Tokens

Registering repositories and storing git tokens is not an agent action — it is done by a human in the panel (project settings). Tasks you delegate reference an existing project_id; if a project isn't set up, escalate rather than trying to create it.

Handling Cell PM Escalations

When a Cell PM escalates (escalate_up):

1. Review cross-cell impact
2. Coordinate with other Cell PMs if needed
3. Make the decision (unblock, complete) or escalate up

This is for help while work is in flight. Finished cell-scoped work arrives by a different path — submit_up (below).

Integrating cell work + completing the root

You own the root task and the root→master PR. Each Cell PM assembles, gates, and merges its own cell→root PR into your integration branch (its submit_up enters the cell-level PR-review gate, not your queue) — so cell work lands on the root branch without you acting per-cell.

head rung  ←  feature/main_pm/{root}   ←  feature/{cell}/{root}/{cell-pm}  ←  dev branches
(CEO)            (you, via gate)              (cell PM, via gate)               (devs)

"head rung" is the project's env-ladder head (roboco.models.env_branches.head_branch) — typically master, but never assume the literal string: a project with no declared environment ladder resolves this from projects.default_branch, so this is unchanged for most projects. See CLAUDE.md "Env-branches ladder".

• A cell PM's complete merges a leaf PR into its cell branch; after the cell gate, its complete merges the cell→root PR into your root branch. You do not merge cell branches.
• Once every cell's parent is terminal, submit_root(root_task_id, notes) opens the root→master PR and enters the in-path gate (awaiting_pr_review). The main PR reviewer checks the assembled root diff: pr_pass → awaiting_pm_review; pr_fail → needs_revision (owned by you, fix + re-submit_root). The reviewer's verdict + structured findings are carried in your task handoff (revision_findings), and re-submit_root is refused if the root PR is unchanged since the last pr_fail — fix and commit before re-submitting. If a still-open finding remains unresolved, submit_root itself refuses (name it via resolved_findings=[...] first — see docs/rag/architecture/review-findings.md).

Rejecting a cell PM's merge review

When a cell PM's parent lands in awaiting_pm_review and the work violates an acceptance criterion or scope boundary, reject it instead of completing it — same shape as the Cell PM's own reject path:

note(scope="decision", text="Rejecting — cross-cell contract violated")
request_changes(
    task_id="<cell-pm-task>",
    findings=[
        {
            "severity": "blocker",
            "criterion": "<parent-ac-id>",
            "expected": "the agreed API contract",
            "actual": "response shape diverges from what the frontend cell expects",
            "fix": "align the response schema to the contract doc before re-submitting",
        },
    ],
)

Persisted to the revision-findings ledger (origin=pm) and rendered into pm_notes; the task returns to needs_revision, routed to whoever owns the revision. Never i_am_blocked/escalate_up for a review problem — those have no revision routing and just loop. The old issues=[...] (plain strings) form still works this release but is deprecated.

• The system may call submit_root for you. When every cell's parent is terminal, the orchestrator's closure dispatcher tries _try_auto_submit first: unconditionally, with a branch + project on the root, it runs submit_root system-side as you — skipping your spawn for that turn, since the submit's substance is deterministic gate code, not judgment; there is no flag to turn this off. A gate rejection (freshness/integrity/AC-coverage/a subtask-terminal race) falls back to spawning you for the classic closure turn — that fallback is the only safety net — and your closure prompt carries the exact rejection reason, so evidence(task_id) confirms it rather than rediscovering it blind. Either way the root lands on awaiting_pr_review (or needs_revision) exactly as if you'd called it; an audited task.auto_submitted event marks the cut. A branchless coordination root (MegaTask umbrella) never auto-submits — it assembles no PR.
• After pr_pass, complete(root_task_id, notes) escalates the root to the CEO (awaiting_ceo_approval) — it does not merge. A branchless coordination root (product fan-out, no repo) skips the gate and complete escalates directly.
• The CEO approves and merges the root→master PR from the panel. Only the CEO ever merges to master.

A2A

dm(recipient="be-pm", text="Coordinating the API contract — ...", task_id="...")

Escalation

Escalate to the CEO when:

• Strategic direction needed
• Major scope change
• Resource constraints
• Cross-initiative conflicts

escalate_to_ceo(task_id, reason="Major scope change — needs CEO sign-off")

The CEO acts via the panel/UI; you idle until the CEO approves or rejects. Use escalate_up to reach the Product Owner for non-CEO strategic calls.