Proposal

A Multi-Agent coachluca Performance Team in OpenClaw

Status: Draft — pre-implementation review
Next document: plan.md (implementation level)

1. Purpose

Define a clean multi-agent coaching architecture for coachluca that works like a real performance staff:

one coordinator with final authority
specialists with narrow domains
one unified athlete-facing voice
durable written records for continuity
one root directory that contains shared materials plus separate per-agent workspaces
strict profile workspace containment for all coaching and athlete materials

This proposal is intentionally high-level. It defines structure and ownership, not implementation steps.

2. Design Priorities

Clear ownership: every decision and artifact has one owner.
Simple operating model: usable inside one OpenClaw profile and one root directory containing separate agent workspaces and shared materials.
Internal depth, external clarity: rich internal reasoning, concise athlete communication.
Durable continuity: important state is written to files, not left in chat context.
Extensibility: new specialists can be added later without redesigning the system.
Profile workspace containment: all coaching-related materials remain inside the profile workspace to preserve one source of truth, simplify backup and inspection, maintain clean operational boundaries, and reduce record fragmentation.

OpenClaw Runtime Assumptions

This architecture assumes OpenClaw runs as separate top-level agents, each with its own workspace and agent state. Human-authored project files live under one profile-owned root directory that contains shared materials plus the per-agent workspaces.

3. Team Structure and Authority

Coordinator: `Coach Luca`

Coach Luca is the single integration point, final decision-maker, and sole communication interface with the athlete. It is the only agent that:

receives all inbound communication from the athlete — messages, updates, questions, check-ins, and media
maintains the athlete planning record (schedule, goals, priority events) as the current source of truth
routes work to specialists
resolves cross-domain conflicts
issues final recommendations
publishes official team reports and all final athlete-facing outputs

The coordinator synthesizes. It does not replace specialist depth.

Specialists (Phase One)

endurance: training structure, load progression, session design and review
nutrition agent: daily fueling, on-bike fueling, hydration, recovery nutrition, nutrition intake logging, and nutritional estimation
recovery: readiness interpretation, fatigue flags, recovery status
strength: gym programming, activation, in-season strength support

Specialists provide recommendations inside their domains only. They do not issue final athlete decisions.

Authority Rule

Shared doctrine sets system-wide rules. Within those rules, the coordinator has final authority over integrated outputs.

Each agent has its own bootstrap identity and instruction files. Shared doctrine is therefore coordinated across agent bootstraps rather than assumed to exist in a single global prompt.

Coach Luca and all specialist agents are responsible for following workspace containment rules whenever they create, update, or manage files.

4. Operating Model

Coordinator receives an inbound request or scheduled trigger.
Coordinator invokes relevant specialists.
Specialists return domain recommendations.
Coordinator resolves conflicts and tradeoffs.
Coordinator produces one unified output.

Specialists do not directly message the athlete and do not override each other. Any inbound communication from the athlete — including replies, questions, and media — is received by Coach Luca and routed internally as needed.

All coaching-related file operations are contained within the profile workspace directory. No coaching records are stored, duplicated, copied, or moved outside that boundary.

5. Boundaries Between Coordinator and Specialists

To prevent role drift:

Specialists analyze and recommend within domain scope.
Coordinator decides and communicates integrated outcomes.
Cross-domain conflicts are escalated to the coordinator, not negotiated laterally between specialists.
Role boundaries are enforced by both instructions and per-agent skill visibility (scoped skills and allowlists).

Typical overlap areas (training vs recovery, nutrition vs recovery, strength vs total load) are expected. The coordinator owns final reconciliation.

Communication Gateway Rule

Coach Luca is the sole communication interface with the athlete. This is a governance rule, not a stylistic preference:

All athlete-facing communication is issued by Coach Luca as one coherent voice.
No specialist may communicate directly with the athlete under any circumstances.
All specialist outputs, questions, and clarifications are internal and must flow through Coach Luca.
Inbound athlete communication is always received and interpreted by Coach Luca before any internal routing occurs.

This boundary prevents fragmented advice, conflicting signals, and ambiguous authority.

6. Information and Reporting Model

The system keeps two output classes with different audiences and purposes.

Cadence by phase:

Specialist working logs are daily.
Coordinator daily and weekly reports are phase one.
Coordinator monthly reporting is phase two.

Workspace Containment Scope

The containment rule applies to all coaching and athlete materials, including:

athlete records
team reports
specialist logs
nutrition items and related nutrition records
planning documents
race and travel schedules
goal and priority records
templates and related working materials

These materials must remain within the profile workspace directory and must not be stored, duplicated, copied, or moved outside it.

Specialist Working Logs (internal inputs)

Each specialist writes a concise daily working log in its own workspace. Purpose: preserve domain reasoning, watch items, and unresolved questions for coordinator synthesis.

Coordinator Reports (official outputs)

The coordinator publishes:

Team reports (internal): reasoning, decisions, tradeoffs, risks
Athlete notes (external): concise, actionable guidance

Rule: athlete-facing notes are derived from coordinator synthesis, not raw specialist outputs.

Athlete Planning Record

The athlete provides two foundational planning inputs to Coach Luca:

Race and travel schedule: upcoming races, travel periods, target events, and key logistical constraints.
Goals and priority events: the races and results that matter most, ranked by athlete importance.

Coach Luca owns the intake and maintenance of this information. It is stored as a dedicated planning record within the profile workspace and serves as a stable reference for the coordinator and relevant specialists.

This record is not passive reference material. It actively shapes training structure, nutrition planning, recovery planning, strength programming, reporting priorities, and tradeoff decisions across the team.

Schedules and priorities change. The planning record should be treated as the current source of truth and updated whenever the athlete's situation changes.

Nutrition Intake Records

The athlete may submit nutrition items — meals, snacks, drinks, supplements — optionally with images and a short description or comment. These are routed to the nutrition agent through the standard coordinator flow. The nutrition agent owns this workflow end to end: it receives the submission, reviews the image and any accompanying text, and forms a practical estimate of what was consumed — including when information is incomplete.

Nutrition items and related records are saved to a nutrition-owned location within the workspace and become part of the ongoing nutrition context. The nutrition agent records each analyzed item in its daily working log: the observed food, the estimated nutritional profile, relevant assumptions, and anything notable for planning.

Estimates from images are recorded as approximations. The nutrition agent uses this information as a direct input to ongoing nutrition planning and monitoring, not as archival data only.

Ownership Rule

Each file has one writer. No agent writes to another agent's owned files.

7. Automation Principles

Use automation only where ownership is clear:

Specialist heartbeat: approximate in-session upkeep and periodic checks
Coordinator cron: precise scheduled reporting and isolated task runs

Automation supports the operating model; it does not define it.

Before athlete-facing reporting automation is fully enabled, outputs should pass a period of manual quality review by the human operator.

8. Scope

Phase One (prove architecture)

coordinator + four specialists (endurance, nutrition agent, recovery, strength)
shared doctrine + per-agent identity files
specialist daily working logs
coordinator daily and weekly team/athlete reporting
manual quality validation before enabling full scheduling cadence

Phase Two (expand after stability)

add performance-analyst
add monthly reporting cadence
enrich synthesis and trend reporting
add optional new specialists without structural redesign

9. Non-Goals

This system does not aim to:

replace medical professionals
fully automate coaching without human oversight
implement every specialist role in phase one
become a full analytics platform before core operations are stable

10. Success Criteria

The proposal is successful when the implemented system can:

Run as one coherent multi-agent coaching team in one root directory with separate per-agent workspaces and shared materials.
Preserve specialist reasoning in durable logs.
Produce coordinator team reports with clear decisions and rationale.
Produce athlete notes that are concise, practical, and clearly separate from internal reasoning.
Maintain unambiguous ownership of decisions and files.
Add a new specialist later without restructuring the whole system.

11. Next Step

On approval, move to plan.md for implementation-level detail:

exact file tree
file ownership map
agent definitions and templates
reporting templates
scheduling configuration
validation checklist

Last updated on 2026-04-13