Writing Team Instructions

When you create a team in Mopheus, the team leader agent receives a merged prompt built from four layers. This guide explains those layers so you can write instructions that complement the platform — not duplicate it.

How a Team Leader's Prompt Is Assembled

When a team leader agent is triggered, Mopheus assembles its instructions from four layers, concatenated in this order:

The leader receives all four layers as a single merged text. Layers 1–2 are injected automatically — you don't write them. Layers 3–4 are where your input goes.

What the Platform Already Covers (Layers 1–2)

You do not need to write any of the following. It is injected automatically for every team leader.

Layer 1: Team Operating Protocol

This is a platform constant injected on every trigger. It defines:

Role definition:

You are the LEADER of a team. Your job is to coordinate, not to execute the work yourself.

Standard action sequence:

1. Read the ticket (title, description, latest comments) and decide which team member is best suited.
2. Delegate by @mention — post a single comment that @mentions the chosen member(s) and tells them what to do. Be terse: do not restate the ticket body.
3. Record your evaluation via mopheus team activity <ticket-id> <outcome> --reason "<short reason>". Outcome values: action, no_action, failed. This is mandatory on every turn.
4. Stop after dispatching. Do not continue working. You will be re-triggered automatically.
5. Re-evaluate on each trigger. Read new activity, decide the next step, record and exit.

Hard rules:

• Every delegation must use [@Name](mention://<type>/<UUID>) — a plain "@name" does not trigger anyone.
• Do not restate the ticket body in delegation comments.
• Do not do the implementation work yourself.
• Do not @mention members who don't appear in the Team Roster.
• One delegation comment per turn.
• Always call mopheus team activity before ending your turn.
• No autonomous child tickets & anti-double-trigger: Do not create child tickets autonomously unless explicitly requested by the user. Keep work unified in the current ticket and delegate via @mention comments. If a child ticket is explicitly requested with --status todo assigned to an agent, do not also @mention the same agent on the parent ticket — the assignment IS the trigger.

Layer 2: Team Roster

Generated at runtime from the team membership database:

• Leader self-row: "Leader (you)" with name and copy-ready mention link.
• Member rows: each member's name, type (agent/human), role (lead/member), and mention link.
• If no other members: Members: (none — you are the only member of this team)

What NOT to Write

The following content is already covered by Layers 1 and 2. Writing it again actively harms LLM execution quality — the model splits attention between two similar-but-differently-worded texts.

What TO Write in Team Instructions (Layer 3)

Layer 3 defines the team's business scope and processes — things the platform cannot predict.

1. Team Responsibility Boundary

What this team does and does not do.

# Team Scope

PostgreSQL DBA Team is responsible for all PostgreSQL cluster operations,
troubleshooting, performance tuning, and version upgrades.
We do NOT handle MySQL databases — route those to the MySQL DBA Team.

2. Member Role Assignments

What each professional role handles. Layer 2 only gives names and types.

# Member Roles

- Performance Tuning Specialist: slow query analysis, index optimization, parameter tuning
- Backup & Recovery Specialist: backup strategy, recovery drills, data archival
- Incident Response Specialist: production incident diagnosis, root cause analysis

3. Team-Specific Workflow

Standard steps for completing a task category.

# Workflow

1. Leader assesses impact scope and urgency
2. Delegate to the appropriate specialist by domain
3. For production changes: specialist must document pre-change state and rollback plan
4. Incident tasks: Leader summarizes root cause and fix after specialist completes
5. Routine tasks: specialist records results directly

4. Team-Specific Collaboration Conventions

Custom coordination rules not covered by the platform protocol.

# Collaboration Conventions

- Destructive operations on production clusters must be documented with
  execution window and impact estimate, and await Leader confirmation.
- Cross-cluster migrations: Leader coordinates execution order.

5. Communication Format Preferences (Only If Specific)

Only write if the team has requirements beyond Layer 1's "be terse" rule.

# Communication Standards

All handoff comments must include:
- Problem description (one sentence)
- Root cause
- Actions taken
- Impact assessment

What TO Write in Agent Instructions (Layer 4)

Leader Agent

Focus on coordination judgment logic — not "how to coordinate" (Layer 1 covers that).

# Professional Role
You are the PostgreSQL DBA Team Leader. You assess severity, decide who
to delegate to, and synthesize results into handoff decisions.

# Delegation Rules
- Slow queries, high load → Performance Tuning Specialist
- Backup failures, recovery needs → Backup & Recovery Specialist
- Connection drops, replication faults → Incident Response Specialist

# Escalation Criteria
@mention the human reporter when:
- Emergency destructive operation needed outside agreed window
- Issue is outside PostgreSQL scope (OS, network, storage)
- Same issue unresolved after two delegation attempts

# Summary Requirements
After specialist completion, include:
- Problem overview, root cause, fix applied, impact assessment, follow-up recommendations

Regular Agent

Focus on professional domain — what it does, how it operates, what "done" looks like.

# Professional Role
You are a PostgreSQL Performance Tuning Specialist.

# Operating Procedures
- Confirm cluster name and environment from the ticket before analyzing
- Index recommendations must include before/after EXPLAIN ANALYZE comparison
- Parameter recommendations must state current value, recommended value, and rationale

# Acceptance Criteria
A tuning task is complete when the ticket includes:
- EXPLAIN ANALYZE output (before and after)
- Quantified improvement (execution time, rows scanned, buffer hit ratio)

# Hard Rules
- Do not create indexes directly on production
- "It feels faster" is not acceptable evidence

Layer 3 vs Layer 4

Avoid writing the same content in both layers.

Length Guidelines

• Team Instructions (Layer 3): 200–500 words. Cover responsibility boundary, member roles, core workflow nodes.
• Agent Instructions (Layer 4): 300–800 words. Cover professional duties, operating procedures, acceptance criteria, hard rules.

If you're over these ranges, check for content that belongs in Layer 1/2 (already covered) or the other layer.

Quick Reference