System Requirements Document for clientforge

1. Introduction

ClientForge is a production-grade agentic SaaS platform for service-based software companies. Its product intent is to make the platform the single source of truth and the primary communication channel for a client project from the moment the human kickoff call ends. A client creates a project after that kickoff call; from then on the client interacts only with their Project Personal Assistant, a persistent AI agent. Human developers and project managers are removed from the day-to-day clarification loop and are engaged only through rare, explicit, well-documented escalation gates.

The audience is the service company and its delivery organisation: the studio owner, delivery lead, or project manager who currently lives inside Jira, Linear, Notion, and Slack, together with the client who is buying the work. The platform is designed for real production projects, not demos, and must optimise, in priority order: eliminating waiting for client replies and reducing miscommunication; keeping the project moving 24/7 with controlled autonomy; escalating to humans only for true business-critical decisions; staying cost-optimised through low token usage, smart model routing, and strong project memory; and delivering faster than traditional human-only teams while maintaining reliability and traceability.

The system is built around a multi-agent architecture with clear roles and inter-agent communication, a strong long-term project memory combining a vector store and a structured store so agents never re-ask known information, a ticket/work-item system that agents create, assign, update, and close, a real-time client chat interface that feels like a personal assistant rather than an interrogator, and human escalation gates that are rare, explicit, and well-documented.

2. System Overview

ClientForge is delivered as a first-party web application with application-owned identity, custom UI, background automation, and generated documents. The current delivery shape is:

• Custom UI: first-party pages for the public entry, identity access, project overview, project setup and brief ingestion, client assistant chat, decisions, the operational project board, escalations, project memory, and the audit trail.
• Application-owned identity: clients self-enrol and establish identity before creating and continuing a project; returning clients, human developers, and human project managers verify identity to resume durable project work. Human developers and human project managers are provisioned before accessing internal operational destinations.
• Background automation: agents keep building, testing, and refining continuously, including while waiting for a client reply.
• Generated documents: the Documentation & Handover Agent produces project documentation and handover material as part of the accepted agent role set.

Actors

Active human personas (closed set):

• Client — the service company's customer whose project begins after the human kickoff call. Chats only with their Project Personal Assistant.
• Human Developer — a human engineer escalated to only for true business-critical or high-technical-risk matters and for conflicting or incomplete client information that agents cannot resolve.
• Human Project Manager — a human PM escalated to alongside developers for critical business logic or product decisions agents cannot reasonably decide, and for unresolvable conflicting or incomplete client information; owns the human-side escalation gates and the kickoff handoff that feeds the structured project brief into the system.

Non-persona actors (systems and agents):

• Project Orchestrator (Project Manager Agent) — owns the overall plan, timeline, dependencies, and status; creates and prioritises tickets; decides which agent handles a task; monitors progress and unblocks other agents; decides when something is truly blocked and needs client or human input.
• Frontend Developer Agent
• Backend Developer Agent
• Full-stack / Integration Agent (engaged when needed)
• QA / Test Agent
• Documentation & Handover Agent
• Client Personal Assistant — the only agent the client talks to.
• Project memory system — vector store plus structured store.
• Ticket / work-item system — shared project board plus structured messages.
• Model routing layer — routes routine work to smaller/faster models and complex reasoning and architecture to larger models.

Accepted behaviour summary

After the human kickoff call, a structured project brief is fed once into the system containing requirements, constraints, tech preferences, success criteria, out-of-scope items, and decision log. From that point the client only chats with their Personal Assistant. Agents communicate through a shared project board plus structured messages, may request clarification from each other or from the Orchestrator, and never go directly to the client — everything routes through the Personal Assistant. Every decision and assumption is logged for full traceability. Escalation to a human occurs only under the three accepted conditions. All other questions are answered by existing project memory, decided by the agents with documented assumptions, or deferred until a natural checkpoint.

Narrow exclusions

• The client interacts only with their Project Personal Assistant; agents never go directly to the client and everything routes through the Personal Assistant.
• Human developers and project managers are removed from the day-to-day clarification loop.
• Escalation to a human is limited to the three accepted conditions; it is not a general-purpose support or review channel.
• The platform is designed for real production projects, not demos.

2a. Product Interpretation and Delivery Boundary

ClientForge is a first-party application. The public entry, identity access, project overview, project setup and brief ingestion, client assistant chat, decisions, project board, escalations, project memory, and audit trail are all owned and rendered by ClientForge itself. There is no provider-owned or external-only surface in the current delivery; the agent workforce, the memory system, the ticket system, and the escalation gates all run inside the platform.

Identity is application-owned. A client can self-enrol before creating a project, and returning clients, human developers, and human project managers verify identity to resume durable project work. Human developers and human project managers are provisioned before they can reach internal operational destinations. Access is role-aware: client communication and decision access is separated from internal board, memory, escalation, and audit access. This separation is a continuity and ownership boundary, not a differentiated-permission feature set beyond what the accepted journeys require.

The current horizon covers everything in the authoritative requirement thread: the multi-agent architecture, the project memory system, the ticket workflow, the Personal Assistant behaviour, the escalation policy, and the MVP a service company can start using immediately after a kickoff call. Nothing in the accepted thread is deferred to a future horizon; the future section records only the success metrics the system should optimise for as ongoing measurement targets rather than as a separate delivery phase.

2c. Page Content and Component Coverage

Landing

• Information/state: anonymous public entry explaining ClientForge, its service-company audience, and its agentic project workflow before identity establishment. Presents the drawn system map of seven colour-coded agent lines converging on the single Client Personal Assistant gate, the oversized headline, the four-stop wayfinding strip (Brief in → Agents work → One question, if it matters → Working software), and the tabular counters for client interruptions, work without human input, and token cost per feature.
• Primary actions: proceed to Sign Up; proceed to Login.
• Supporting actions: read the numbered section dividers (01 ARCHITECTURE, 02 MEMORY, 03 TICKETS, 04 ESCALATION, 05 MVP); read the schematic supporting imagery (memory-store diagram, ticket lifecycle wayfinding strip, escalation policy decision pictogram); view the documentary photograph in the "How it runs in a real studio" section.
• Domain entities: agent role, agent line colour, Personal Assistant gate, wayfinding stop, success-metric counter.
• Component responsibilities: hero network map; headline block; wayfinding strip with tabular counters; primary ink CTA button with 2px bottom edge; secondary text link with colour-coded rule; numbered section dividers; schematic imagery blocks; studio photograph block.
• States: loading (map and counters render, counters tick up once on reveal); empty (not applicable — static public content); success (page renders, counters settle at their values); error (map or counter asset fails to load — text content remains readable, counters show their last known value); recovery (reload or continue to Sign Up or Login).

Login

• Information/state: returning verification surface for Clients, Human Developers, and Human Project Managers to resume access to durable project work.
• Primary actions: submit credentials to verify identity and resume access.
• Supporting actions: navigate to Sign Up; return to Landing.
• Domain entities: identity, role, session.
• Component responsibilities: credential form; submit control; error region; link to Sign Up.
• States: loading (submit in progress); empty (form fields blank); success (identity verified, routed to the destination appropriate to the role); error (invalid credentials — inline message, form retained); recovery (retry, or navigate to Sign Up).

Sign Up

• Information/state: first-use enrolment path for a self-starting Client before creating and continuing a project.
• Primary actions: establish a Client identity.
• Supporting actions: navigate to Login; return to Landing.
• Domain entities: identity, role, session.
• Component responsibilities: enrolment form; submit control; error region; link to Login.
• States: loading (submit in progress); empty (form fields blank); success (identity established, routed to Projects); error (invalid or incomplete enrolment — inline message, form retained); recovery (correct and resubmit, or navigate to Login).

Projects

• Information/state: revisitable project overview for entering projects and continuing project work after kickoff. Lists the Client's and Human Project Manager's projects with their current state.
• Primary actions: open a project; start a new project.
• Supporting actions: review project state at a glance; navigate to Project Setup.
• Domain entities: project, project state, kickoff status, brief ingestion status.
• Component responsibilities: project list as a ruled table with tabular IDs and 3px line-colour rules; project state chip; new-project control; empty-state block.
• States: loading (list skeleton); empty (no projects yet — centred empty state with a start-project action); success (projects listed); error (list fails to load — retry control, last known list retained where available); recovery (retry, or start a new project).

Project Setup

• Information/state: focused project creation and one-time structured kickoff-brief ingestion workspace. Captures the structured project brief containing requirements, constraints, tech preferences, success criteria, out-of-scope items, and decision log.
• Primary actions: create the project; feed the structured project brief once into the system.
• Supporting actions: review the captured brief before submission; return to Projects.
• Domain entities: project, structured project brief, requirement, constraint, tech preference, success criterion, out-of-scope item, decision log entry.
• Component responsibilities: project creation form; brief ingestion form with a section per brief field; submission control; validation region; confirmation of one-time ingestion.
• States: loading (submission in progress); empty (no brief captured yet); success (project created and brief ingested once, routed to Assistant Chat or Project Board); error (validation failure or ingestion failure — inline message, captured content retained); recovery (correct and resubmit; re-open the workspace to complete a partially captured brief).

Assistant Chat

• Information/state: protected real-time communication destination where the Client interacts only with the persistent Project Personal Assistant. Two-pane split: conversation on the left at a 68ch measure, and a pinned "What the agents decided" ledger on the right that updates as assumptions are logged.
• Primary actions: send a message to the Personal Assistant; respond to a surfaced high-impact decision.
• Supporting actions: read progress updates in plain language; read the pinned decision ledger with timestamps and links to the triggering ticket; follow a ledger link to the relevant ticket.
• Domain entities: conversation message, Personal Assistant, decision ledger entry, assumption, timestamp, triggering ticket.
• Component responsibilities: conversation pane; message composer; decision ledger pane; ledger entry with timestamp and ticket link; Personal Assistant voice styling in accent colour.
• States: loading (conversation history and ledger load); empty (no messages yet — Personal Assistant opens the conversation); success (message sent and acknowledged; ledger updated); error (message fails to send — message retained in composer with a retry control); recovery (retry send; reload conversation and ledger).

Decisions

• Information/state: focused workspace for high-impact client decisions, documented assumptions, recommendations, and natural checkpoints. Surfaces only high-impact decisions such as pricing logic, major UX flows, and compliance rules.
• Primary actions: review a surfaced decision with its recommendation; approve the recommendation; decide differently.
• Supporting actions: read the documented assumptions behind a decision; read the recommendation; defer a decision to a natural checkpoint where the accepted behaviour allows.
• Domain entities: decision, recommendation, documented assumption, natural checkpoint, decision outcome.
• Component responsibilities: decision list; decision card with recommendation and assumptions; approve-recommendation control; decide-differently control; checkpoint indicator.
• States: loading (decision list loads); empty (no decisions awaiting the client — centred empty state); success (decision recorded and reflected in the ledger); error (decision submission fails — card retained with a retry control); recovery (retry submission; re-open the decision).

Project Board

• Information/state: operational board for plans, tickets, assignments, dependencies, agent messages, progress, and continuous work. Rendered as a ruled table, not a card grid: columns are agent roles, rows are tickets, and each row carries an ID, a line-colour rule, an owner chip, a state, and a token-cost figure in tabular numerals.
• Primary actions: inspect a ticket; inspect an agent assignment; inspect a dependency; read structured agent messages.
• Supporting actions: filter the board to a single agent line; read plan, timeline, and status; read progress and continuous-work state.
• Domain entities: plan, timeline, dependency, ticket, ticket ID, owner chip, ticket state, token cost, structured agent message, agent role.
• Component responsibilities: ruled board table; ticket row with ID, 3px line-colour rule, owner chip, state, and token-cost figure; agent-role columns; filter control; structured-message region; agent-status rail with a 2px line-colour dot pulsing only while an agent is actively working.
• States: loading (board skeleton); empty (no tickets yet — centred empty state); success (board populated, rows snap between states with a single colour wipe along the left rule); error (board fails to load — retry control, last known board retained where available); recovery (retry; filter to a single agent line to reduce load).

Escalations

• Information/state: focused human escalation queue for critical business decisions, high technical risk, and unresolved client information. Escalation cards are the only place red appears: solid #B91C1C fill, a warning pictogram, a numbered reason code (E1 business logic, E2 security/data integrity, E3 conflicting brief), and a two-button resolution.
• Primary actions: review an escalation; approve the recommendation; decide differently.
• Supporting actions: read the numbered reason code; read the supporting context and the audit trail entry behind the escalation.
• Domain entities: escalation, reason code (E1, E2, E3), recommendation, resolution outcome, escalation owner.
• Component responsibilities: escalation queue; escalation card with solid red fill, warning pictogram, reason code, and two resolution buttons; resolution control; link to the related audit trail entry.
• States: loading (queue loads); empty (no escalations — centred empty state); success (escalation resolved and recorded); error (resolution submission fails — card retained with a retry control); recovery (retry resolution; re-open the escalation).

Project Memory

• Information/state: revisitable view of durable structured and vector-backed project context and compressed knowledge, so agents never re-ask known information.
• Primary actions: inspect structured project context; inspect vector-backed knowledge; inspect compressed knowledge.
• Supporting actions: search or filter memory entries; follow a memory entry to its source.
• Domain entities: structured memory record, vector-backed memory entry, compressed knowledge, source reference.
• Component responsibilities: structured-store view; vector-store view; compressed-knowledge view; search/filter control; source link.
• States: loading (memory views load); empty (no memory entries yet — centred empty state); success (memory populated); error (memory fails to load — retry control, last known view retained where available); recovery (retry; narrow the search or filter).

Audit Trail

• Information/state: traceability destination for agent actions, decisions, assumptions, code changes, reliability events, and rollback records.
• Primary actions: inspect an agent action; inspect a decision or assumption; inspect a code change; inspect a reliability event or rollback record.
• Supporting actions: filter the trail by agent, ticket, or event type; follow an entry to its related ticket or escalation.
• Domain entities: agent action, decision, assumption, code change, reliability event, rollback record, timestamp, actor.
• Component responsibilities: chronological trail list; entry with actor, timestamp, and event type; filter control; link to related ticket or escalation.
• States: loading (trail loads); empty (no entries yet — centred empty state); success (trail populated); error (trail fails to load — retry control, last known trail retained where available); recovery (retry; narrow the filter).

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance.

FR-1 — Multi-agent architecture with clear roles and inter-agent communication (explicit) As a service company, I should have a multi-agent system with clear roles and inter-agent communication so that work is routed to the right agent without human coordination.

• Actor: service company (system owner); agents as non-persona actors.
• Trigger/input: project work exists on the shared project board.
• Observable result: agents with distinct roles (Project Orchestrator, Frontend Developer, Backend Developer, Full-stack/Integration, QA/Test, Documentation & Handover, Client Personal Assistant) communicate through the shared project board and structured messages.
• Access state: internal operational access.
• Failure/recovery: if an agent cannot complete its task, it requests clarification from another agent or from the Orchestrator.
• Continuation: the Orchestrator monitors progress and unblocks other agents.

FR-2 — Project Orchestrator owns plan, timeline, dependencies, and status (explicit) As a Project Orchestrator, I should own the overall plan, timeline, dependencies, and status so that the project has a single authoritative schedule.

• Actor: Project Orchestrator.
• Trigger/input: project brief ingested.
• Observable result: plan, timeline, dependencies, and status are maintained and visible on the Project Board.
• Access state: internal operational access.
• Failure/recovery: if a dependency blocks progress, the Orchestrator decides whether the block is true.
• Continuation: the Orchestrator continues to monitor and update status.

FR-3 — Project Orchestrator creates and prioritises tickets (explicit) As a Project Orchestrator, I should create and prioritise tickets so that work is ordered and visible.

• Actor: Project Orchestrator.
• Trigger/input: plan and dependencies.
• Observable result: tickets exist on the Project Board with priority and state.
• Access state: internal operational access.
• Failure/recovery: if a ticket cannot be prioritised, the Orchestrator defers it until a natural checkpoint.
• Continuation: tickets move through create, assign, update, and close.

FR-4 — Project Orchestrator decides which agent handles a task (explicit) As a Project Orchestrator, I should decide which agent handles a task so that work is routed to the correct role.

• Actor: Project Orchestrator.
• Trigger/input: a ticket requiring an owner.
• Observable result: the ticket carries an owner chip for the assigned agent role.
• Access state: internal operational access.
• Failure/recovery: if no agent can handle the task, the Orchestrator decides whether it is truly blocked.
• Continuation: the assigned agent picks up the ticket.

FR-5 — Project Orchestrator monitors progress and unblocks other agents (explicit) As a Project Orchestrator, I should monitor progress and unblock other agents so that the project keeps moving.

• Actor: Project Orchestrator.
• Trigger/input: agent progress or a blocked agent.
• Observable result: blocked agents are unblocked or the block is escalated.
• Access state: internal operational access.
• Failure/recovery: if the block cannot be resolved internally, the Orchestrator decides whether it needs client or human input.
• Continuation: work resumes.

FR-6 — Project Orchestrator decides when something is truly blocked and needs client or human input (explicit) As a Project Orchestrator, I should decide when something is truly blocked and needs client or human input so that escalation is rare and deliberate.

• Actor: Project Orchestrator.
• Trigger/input: a block that cannot be resolved by agents.
• Observable result: the block is routed to the Personal Assistant (for the client) or to an escalation (for a human), or is deferred to a natural checkpoint.
• Access state: internal operational access.
• Failure/recovery: if the block is not truly blocking, it is answered by existing project memory or decided by the agents with documented assumptions.
• Continuation: the project continues.

FR-7 — Frontend Developer Agent (explicit) As a Frontend Developer Agent, I should build frontend work items assigned to me so that the client-facing product is implemented.

• Actor: Frontend Developer Agent.
• Trigger/input: an assigned frontend ticket.
• Observable result: the ticket is updated and closed with the frontend work recorded.
• Access state: internal operational access.
• Failure/recovery: if the work is blocked, the agent requests clarification from another agent or from the Orchestrator.
• Continuation: the ticket moves to QA.

FR-8 — Backend Developer Agent (explicit) As a Backend Developer Agent, I should build backend work items assigned to me so that the server-side product is implemented.

• Actor: Backend Developer Agent.
• Trigger/input: an assigned backend ticket.
• Observable result: the ticket is updated and closed with the backend work recorded.
• Access state: internal operational access.
• Failure/recovery: if the work is blocked, the agent requests clarification from another agent or from the Orchestrator.
• Continuation: the ticket moves to QA.

FR-9 — Full-stack / Integration Agent (when needed) (explicit) As a Full-stack / Integration Agent, I should handle integration work when needed so that frontend and backend work connect.

• Actor: Full-stack / Integration Agent.
• Trigger/input: an assigned integration ticket, engaged when needed.
• Observable result: the ticket is updated and closed with the integration work recorded.
• Access state: internal operational access.
• Failure/recovery: if the work is blocked, the agent requests clarification from another agent or from the Orchestrator.
• Continuation: the ticket moves to QA.

FR-10 — QA / Test Agent (explicit) As a QA / Test Agent, I should test work items so that quality is verified before completion.

• Actor: QA / Test Agent.
• Trigger/input: a ticket ready for testing.
• Observable result: the ticket is updated with the test outcome and closed or returned.
• Access state: internal operational access.
• Failure/recovery: if a test fails, the ticket is returned to the owning agent.
• Continuation: the ticket is retested or closed.

FR-11 — Documentation & Handover Agent (explicit) As a Documentation & Handover Agent, I should produce documentation and handover material so that the delivered project is documented.

• Actor: Documentation & Handover Agent.
• Trigger/input: completed work items.
• Observable result: documentation and handover material are generated and recorded.
• Access state: internal operational access.
• Failure/recovery: if documentation cannot be completed, the agent requests clarification from another agent or from the Orchestrator.
• Continuation: the documentation is updated as work continues.

FR-12 — Client Personal Assistant is the only agent the client talks to (explicit) As a Client Personal Assistant, I should be the only agent the client talks to so that the client has a single, consistent point of contact.

• Actor: Client Personal Assistant.
• Trigger/input: client messages and agent requests routed through the Personal Assistant.
• Observable result: all client-facing communication flows through the Personal Assistant; agents never go directly to the client.
• Access state: protected client communication access.
• Failure/recovery: if the Personal Assistant cannot answer, it routes the question to the Orchestrator or surfaces a decision.
• Continuation: the conversation continues.

FR-13 — Structured project brief fed once after the kickoff call (explicit) As a Human Project Manager, I should feed a structured project brief once into the system after the human kickoff call so that the project starts from a complete, authoritative brief.

• Actor: Human Project Manager (kickoff handoff).
• Trigger/input: a completed human kickoff call.
• Observable result: the structured project brief containing requirements, constraints, tech preferences, success criteria, out-of-scope items, and decision log is ingested once.
• Access state: role-restricted project setup access.
• Failure/recovery: if ingestion fails or the brief is incomplete, the workspace retains captured content for correction and resubmission.
• Continuation: the project begins autonomous execution.

FR-14 — Client creates a project after the kickoff call (explicit) As a Client, I should create a project after the kickoff call so that the platform becomes the single source of truth and the primary communication channel.

• Actor: Client.
• Trigger/input: a completed human kickoff call.
• Observable result: the project exists and is listed on Projects.
• Access state: role-restricted project access.
• Failure/recovery: if creation fails, the workspace retains captured content for correction and resubmission.
• Continuation: the client proceeds to Assistant Chat.

FR-15 — Platform is the single source of truth and primary communication channel (explicit) As a Client, I should have the platform be the single source of truth and the primary communication channel so that I do not need to coordinate through other channels.

• Actor: Client.
• Trigger/input: project created.
• Observable result: project state, decisions, and communication live in the platform.
• Access state: role-restricted project access.
• Failure/recovery: if a channel is unavailable, the platform retains state and resumes.
• Continuation: the client continues in Assistant Chat.

FR-16 — Client interacts only with their Project Personal Assistant (explicit) As a Client, I should interact only with my Project Personal Assistant so that I am not exposed to the agent workforce directly.

• Actor: Client.
• Trigger/input: client opens Assistant Chat.
• Observable result: the client's conversation is with the Personal Assistant only.
• Access state: role-restricted client communication access.
• Failure/recovery: if the Personal Assistant cannot answer, it routes internally and responds.
• Continuation: the conversation continues.

FR-17 — Human developers and project managers removed from the day-to-day clarification loop (explicit) As a service company, I should have human developers and project managers removed from the day-to-day clarification loop so that delivery is not gated on human availability.

• Actor: service company.
• Trigger/input: day-to-day clarification needs.
• Observable result: clarifications are answered by project memory, decided by agents with documented assumptions, or deferred to a natural checkpoint.
• Access state: internal operational access.
• Failure/recovery: