Multi-Agent Structure for PSSaaS

Date: 2026-04-16 Agent: Collaborator Scope: Define three specialized AI agent roles and the handoff machinery between them.

Why

PowerFill Phase 0 consumed 10K+ lines of markdown output in a single session and the quality bar required extra care to maintain. Phase 1-9 is 12-16 weeks of implementation work ahead. One agent trying to be Product-Owner-partner + specification author + code reviewer + developer is an anti-pattern at this scale.

The PSX project has been running a three-role structure (Collaborator, Software Architect, Infrastructure) for months — we adopted the same pattern with PSSaaS-specific adjustments.

What Was Done

Created a full multi-agent operating framework:

• docs-site/docs/agents/README.md — overview of the three roles, delegation patterns, role identification procedure
• docs-site/docs/agents/collaborator-context.md — formalizes the default role (what I've been doing)
• docs-site/docs/agents/architect-context.md — operating manual for the Systems Architect
• docs-site/docs/agents/developer-context.md — operating manual for Developer agents (fast subagents, manual relays, or the Architect itself)
• docs-site/docs/agents/handoff-prompts.md — seven template prompts for role transitions (Collaborator→Architect, Architect→Developer, escalations, PO questions, alignment checkpoints, devlog entries)
• docs-site/docs/agents/powerfill-architect-kickoff.md — specific prompt Kevin pastes to bootstrap the Architect on PowerFill Phase 1

Updated CLAUDE.md with a role-identification procedure at the top — matches PSX's pattern where every session must identify its role before taking action. This prevents the PSX failure mode (2026-04-13) where an agent resumed from a context summary, assumed the wrong role, and edited the wrong handoff.

Updated AGENTS.md with delegation rules and lessons learned.

Updated the session handoff to reflect strategic discovery #26.

Added an Agent Roles category to the Docusaurus sidebar.

Key Decisions

• Three roles, not four. No dedicated PSSaaS Infrastructure agent yet — the PSX Infra Agent handles shared cluster work, and the Collaborator handles PSSaaS-local infra (kubectl, SQL queries, Docker). Promote to a dedicated role when infra work grows.
• Role identification is first action. Every agent checks its role at session start. No silent role assumption.
• Plan mode for non-trivial design. The Architect defaults to Plan mode for anything multi-file.
• Templates are mandatory. Handoffs use the templates in handoff-prompts.md verbatim — paraphrasing creates scope ambiguity.
• Developers can be fast subagents, manual relays, or the Architect itself. Dispatch mode chosen per task complexity.

What's Next

Kevin pastes the PowerFill Architect kickoff prompt into a new Cursor session. The Architect onboards itself, reads Phase 0 artifacts, studies the BestEx reference patterns, and produces a Phase 1 implementation plan. Kevin reviews the plan and approves execution. Architect delegates or self-implements.

Risks Captured

• Cross-session coordination must go through committed files. Architect and Collaborator are in separate Cursor sessions. All decisions must be captured in devlog/handoff/spec, not just conversation.
• Version drift across role context docs. As we learn, we'll update role docs. Must keep them in sync or agents will behave inconsistently.
• Cursor's multiple-session UX. Kevin will juggle the Collaborator window, the Architect window, and possibly Developer windows. Discipline in session labeling matters.
• Cost. Running an additional agent costs tokens. The trade-off: better quality (fewer mistakes to correct), faster work (parallelism), cheaper per-task (fast subagents / Cursor Auto for mechanical work). Net should be positive.