my-mcp-agent-orchestrator

Imported from SETA1609/my-mcp-agent-orchestrator (AGENTS.md). Install upstream with npx skills add SETA1609/my-mcp-agent-orchestrator. Copyright stays with the author.

AGENTS

This is the master coordination document. Every agent working in this repository must read this file before touching any code.

Agent Roster

Agent Strength Guide

Use this table at planning time to assign phases to agents whose strengths match the type of work. This is a guide — it does not override the [Primary|Fallback] notation in PLAN.md.

Planning for Parallelism

When writing or updating PLAN.md, the goal is maximum concurrent throughput:

The one gate: Phase 1

Phase 1 is the only serialization point. It must define every shared interface, module boundary, and scaffold file that later phases depend on. No other agent should start implementation work until Phase 1 is complete.

Phase 1 deliverables (at minimum):

• Go module initialised (go.mod, go.sum)
• All internal/ package skeletons created (empty files with correct package declarations)
• Public interfaces defined (e.g. Transport, capability registration signatures)
• Dependency pinned (go.mod with correct SDK version)

After Phase 1: full parallelism

Every phase after Phase 1 must be designable to run concurrently. Achieve this by:

1. Assign distinct file areas per phase. No two phases should own the same file. Use the File Ownership table to verify before finalising the plan.
2. Match phase type to agent strength. Use the Agent Strength Guide above. A phase for boilerplate goes to [P]; a phase for reasoning-heavy design goes to [GR] or [K].
3. No cross-phase dependencies (after Phase 1). If Phase 3 requires Phase 2 output, either collapse them or move the dependency into Phase 1.
4. All agents should be able to start their phase simultaneously once Phase 1 merges to main.

Example layout

Phase 1  [C|K]   — scaffold: interfaces, stubs, module init        ← GATE
Phase 2  [O|G]   — transport layer (internal/transport/)           ┐
Phase 3  [P|GF]  — config + logging (internal/config/, cmd/)       │ all run
Phase 4  [K|C]   — algorithms / complex tools (internal/tools/)    │ in parallel
Phase 5  [O|G]   — Docker packaging (Dockerfile, compose)          │ after Phase 1
Phase 6  [K|C]   — test harness + CI (.github/, tests/)            ┘

Checklist before finalising a plan

• Phase 1 covers every shared contract other phases depend on
• Each post-Phase-1 phase touches a distinct directory or file set
• Each phase is assigned to an agent whose strength matches the work type
• No phase after Phase 1 lists another post-Phase-1 phase as a prerequisite

Before You Start

1. Read PLAN.md — understand the active work manifest before touching any files.
2. Read your detail file in docs/agents/ for role boundaries, co-author trailer, and context files.
3. Read the relevant docs/ files for the layer you will be working on.
4. Do not start work on a step that is already claimed by another agent symbol.

Step Claiming Protocol

PLAN.md lists all work as numbered steps. Each step starts unclaimed [ ] and lists the agents eligible to work it.

Eligibility notation

Steps use [Primary|Fallback] to show which agents may claim them, in priority order:

- [ ] [C|K]     → C should take this; K may take it if C is unavailable
- [ ] [O|G]     → O should take this; G may take it if O is unavailable
- [ ] [GF|P]    → Grok Code Fast should take this; Copilot may fall back
- [ ] [D]       → human only, no fallback

Claiming a step

1. Check eligibility — only claim a step if your symbol appears in the step's eligibility list.
2. Claim — replace [ ] with your own symbol, then commit that change alone before doing any other work.
3. Work the step.
4. Complete — replace your symbol with [x] and commit before moving to the next step.
5. Only one agent may hold a symbol on any given step at a time.
6. Never skip a step unless it is explicitly marked optional.

Example progression:

- [ ] [C|K]   →  - [C] [C|K]   →  - [x] [C|K]    (Claude claimed and completed)
- [ ] [O|G]   →  - [G] [O|G]   →  - [x] [O|G]    (Gemini took it as fallback)
- [ ] [GF|P]  →  - [GF] [GF|P] →  - [x] [GF|P]   (Grok Code Fast claimed and completed)

Role Boundaries

[C] Claude

• Designs new abstractions, base classes, and framework-level systems
• Writes and maintains PLAN.md
• Unblocks other agents by defining interfaces they can build against
• Cannot be bypassed — [G], [P], and [O] must not introduce new abstractions without a [C] or [K] handoff step first
• See docs/agents/CLAUDE.md for full detail

[G] Gemini

• Refactors and extends existing abstractions
• Implements UI/view-layer features
• Carries out clearly scoped minor tasks
• Cannot introduce new abstractions or design framework systems without a prior [C]/[K] step
• See docs/agents/GEMINI.md for full detail

[K] Codex

• Designs and implements complex algorithms and data structures
• Produces detailed implementation proposals for human review
• Plans new subsystems with clear interfaces for other agents to build against
• See docs/agents/OPENCODE.md for full detail (runs via Copilot)

[P] Copilot

• Fills in boilerplate and repeat patterns already established
• Implements simple, self-contained utilities (single file)
• Cannot design APIs, introduce abstractions, or touch shared/critical code without prior [C]/[K] authorization
• See docs/agents/OPENCODE.md for full detail (Copilot rules live there — OpenCode always reads it)

[O] OpenCode

• Implements features end-to-end once interfaces are defined by [C] or [K]
• Handles code generation and scaffolding within existing patterns
• Cannot change public interfaces without a prior [C]/[K] design step
• Must use its actual running model name in the co-author trailer — not the generic "OpenCode" label
• See docs/agents/OPENCODE.md for full detail

[GF] Grok Code Fast

• Speed-first: writes or fixes single files quickly with minimum overhead
• Best for quick patches, filling in function bodies, one-off scripts
• Cannot introduce new abstractions or design cross-file patterns
• See docs/agents/OPENCODE.md for full detail (runs via Copilot)

[GR] Grok 4.20

• Reasoning-heavy tasks: multi-step deduction, root-cause analysis, algorithm design
• Can propose design changes but must hand off to [C]/[K] for implementation contracts
• Use when a task requires careful logical reasoning, not just code generation
• See docs/agents/OPENCODE.md for full detail (runs via OpenCode)

[PK] Pickle

• Rapid prototyping and experimental spikes
• Output is a working sketch — not intended for production without review by [C] or [K]
• Cannot merge prototype code to main without [D] approval

[D] Human

• Approves or rejects plans before implementation starts
• Resolves conflicts between agents
• Makes all irreversible architectural decisions

File Ownership

Workflows

Reusable workflows live in .agents/workflows/. Run them as needed:

• build.md — build and report errors
• commit.md — stage and commit with correct format and co-author trailers
• review.md — review changed files for quality and architecture violations
• update-docs.md — sync docs/PROJECT_TREE.md and other docs after code changes

Git Rules

• Commit format: <type>: <description> — see docs/COMMIT_STYLE.md
• Every commit must include your agent's co-author trailer (see your detail file in docs/agents/)
• Never force-push to main
• Open a PR for any change that touches shared or framework-level code

Branch & merge strategy (squash + rebase + fast-forward)

Every task is worked in its own short-lived branch. Agents work simultaneously — no locking required. The rebase step before merge is what keeps main linear without coordination.

# 1. Branch off main before touching any files
git checkout main && git pull --ff-only
git checkout -b <agent>/<short-description>   # e.g. c/transport-interface

# 2. Do your work — commit as often as needed while working
git add <files>
git commit -m "wip: ..."

# 3. Squash all branch commits into one
git rebase -i main   # mark every commit except the first as "squash"
# Write the final commit message following COMMIT_STYLE.md (with co-author trailers)

# 4. Rebase onto the latest origin/main (handles any merges by other agents while you worked)
git fetch origin
git rebase origin/main

# 5. Fast-forward main — guaranteed clean because you just rebased
git checkout main
git pull --ff-only
git merge --ff-only <agent>/<short-description>

# 6. Push and delete the branch
git push
git branch -d <agent>/<short-description>

Why this works without locking: Steps 3–5 are the key. Squash first so the rebase in step 4 moves a single clean commit — not a pile of wip commits. If another agent merged while you were working, rebase origin/main replays your one commit on top of their work. As long as agents respect file ownership, rebases are conflict-free.

If the rebase in step 4 has a conflict:

1. Resolve the conflict in the affected file
2. git add <file> && git rebase --continue
3. If unresolvable, git rebase --abort and coordinate with [D]

Rules:

• One branch per PLAN.md step — do not batch multiple steps into one branch
• Branch name format: <agent-symbol-lowercase>/<kebab-description> (e.g. c/transport-interface, o/stdio-impl)
• Always git fetch origin before rebasing — never rebase onto stale local main
• The squashed commit message must follow docs/COMMIT_STYLE.md and include all co-author trailers
• Never merge with --no-ff — no merge commits on main
• Never force-push main