PSSaaS Multi-Agent Structure
PSSaaS uses three specialized AI agent roles plus Kevin (Product Owner) as the human in the loop. This document defines the roles, their responsibilities, and how work flows between them.
The Four Participants
Role Boundaries
| Role | Owns | Does Not Own |
|---|---|---|
| Product Owner (Kevin) | Strategic direction, backlog priority, architectural approval, git push, team relationships (Tom/Greg/Jay/Lisa) | Code implementation, spec drafting, infrastructure operations |
| Collaborator | Product-Owner partnership, value discovery, team-meeting prep, roadmap reasoning, cross-project coordination (PSX/MBS Access/Desktop App), agent dispatch, git commits | Deep spec writing, detailed ADR drafting, implementation code, infrastructure changes outside PSSaaS |
| Systems Architect | Specs, ADRs, implementation plans, code design, code review, developer task prompts, assumptions logs, technical risk analysis | Strategic decisions, backlog priority, cross-product coordination, user-facing conversations, git push |
| Developer Agent(s) | Implementation against architect-provided task prompts, unit tests, integration tests, code quality | Architectural decisions, spec changes, cross-module redesign, infrastructure operations |
| PSX Infrastructure Agent | AKS cluster, Superset deployment, DNS, Azure resources, psx-staging and pss-platform namespaces | PSSaaS code, PSSaaS specs, product decisions |
Role Identification on Session Start
Cursor loads CLAUDE.md automatically for every session. Because three roles share the same repo, every agent must identify its own role before taking action:
- Check the session's initial prompt — it should begin with "You are the PSSaaS
<role>agent." or include a role-specific kickoff. - If resuming from a context summary, look for role markers in the summary header.
- If still unclear, ask Kevin which role you are. Do not guess.
- Once role is confirmed, read your role-specific context doc:
- Collaborator → collaborator-context.md
- Systems Architect → architect-context.md
- Developer → developer-context.md
- Then read the shared invariants (CLAUDE.md, AGENTS.md, session handoff).
Why this matters: PSX has learned (the hard way) that an agent resuming from a summary can assume the wrong role, edit the wrong handoff, and destroy trust. See PSX's CLAUDE.md header for the full story. We adopt the same discipline.
Delegation Patterns
Kevin → Collaborator
Default conversation — Kevin starts every session with the Collaborator unless explicitly invoking another role.
Collaborator → Systems Architect
When Kevin approves a design effort (new spec, new ADR, new module), the Collaborator:
- Writes a structured handoff using the template in handoff-prompts.md
- Kevin reviews the handoff and decides whether to:
- Spawn a new Cursor session and paste the handoff to bootstrap the Architect
- Continue letting the Collaborator do the work (for small efforts)
Systems Architect → Developer
When the Architect has a concrete, narrow, well-specified implementation task, it chooses one of three dispatch modes:
- Fast subagent (via the Task tool,
subagent_type: generalPurpose) for mechanical tasks: scaffolding, entity class generation, unit test templates, SQL formatting. Same Cursor session, no human relay. - Manual relay prompt written for Kevin to paste into Cursor Auto or Sonnet. Used for non-trivial implementation that benefits from a different model's perspective or a separate session context.
- Self (the Architect implements directly) for tasks that need full Architect context.
See developer-context.md and handoff-prompts.md for the task prompt template.
Architect → Collaborator Escalation
The Architect escalates back when it hits:
- A decision requiring Product Owner input (e.g., "should this be a new module or an extension of BestEx?")
- A cross-product concern (e.g., "this spec implies a change to the PSX data contract")
- A business rule that isn't clear from the spec (e.g., "what should happen when constraint A and constraint B both apply?")
- A scope question (e.g., "this phase is larger than estimated")
Escalations use the template in handoff-prompts.md. The Collaborator either answers from established context, asks Kevin, or raises the question in the next Kevin conversation.
Any Agent → Kevin
Any agent can ping Kevin at any time. The higher-specialization agents (Architect, Developer) should generally route through the Collaborator unless the question is narrowly scoped to their role.
Shared Context Documents
All three agent roles read:
CLAUDE.md— project identity, invariants, role-identification procedureAGENTS.md— agent memory: principles, lessons, preferences.cursorrules— development rulesdocs-site/docs/handoffs/pssaas-session-handoff.md— current platform state
All three write to:
docs-site/docs/devlog/— one entry per completed task, regardless of roledocs-site/docs/handoffs/pssaas-session-handoff.md— updated at alignment checkpoints by whichever agent runs the checkpoint
Role-specific documents:
docs-site/docs/agents/<role>-context.md— role definition and operating rulesdocs-site/docs/specs/— owned by Systems Architect (all drafting and updates)docs-site/docs/adr/— owned by Systems Architect (drafting); approved by Kevindocs-site/docs/legacy/— owned by Systems Architect (reverse-engineering docs)docs-site/docs/agents/handoff-prompts.md— owned by Collaborator (template maintenance)
Current Roster
| Role | Status | Cursor Session |
|---|---|---|
| Collaborator | Active (default) | Main PSSaaS project window |
| Systems Architect | Not yet spawned | Will be a separate Cursor session |
| Developer | On-demand via Task tool or manual relay | N/A |
| PSX Infrastructure | Active | PSX project window |
When to Bring Up a New Agent
Rule of thumb: add a new specialized agent when the current agent's context load is degrading output quality.
Signals that PSSaaS needs the Systems Architect now:
- PowerFill Phase 0 spec + ADRs + deep dive took 10K+ lines in one session — any more and quality would have suffered
- PowerFill Phase 1-9 is 12-16 weeks of implementation work that Kevin cannot reasonably supervise in a single Collaborator session
- Parallel work streams are about to emerge (PowerFill + MIAC SRP + PSX BestEx integration + more dashboards)
Signals that a dedicated PSSaaS Infrastructure agent should be spawned:
- Deployment frequency increases beyond the PSX infra agent's capacity
- PSSaaS-specific infra work (SQL MI tenancy, .NET deployment patterns) becomes a full-time concern
- We're not there yet
Versioning
This document and the other docs-site/docs/agents/*.md files are versioned in the repo so all agents reference the same operating procedures. Changes require Product Owner review.