System Requirements Document for ai-agents

1. Introduction

My Assistant — Your AI Employees. One Intelligent Platform. — is an AI-powered SaaS workspace in which specialized AI agents ("AI Employees") research, plan, organize, automate workflows, use authorized tools, and deliver verifiable results under appropriate user approval. The product is not a question-answering chatbot; it is a coordinated workforce that acts on real business tasks and reports honestly on what it actually did.

The current delivery is the first MVP: one complete Lead Generation AI Employee for digital marketing agencies, implemented end to end — natural-language task entry, AI interpretation, authorized-source or user-dataset gathering, validation/deduplication/structuring, storage in a database or connected spreadsheet, visible progress and final results, human review and approval of external outreach, execution of approved actions through an authorized integration, and recorded results, errors, and completion status.

The audience for this document is the engineering team building the platform, and the audience for the product is the initial customer set: digital marketing and SEO agencies, startups and SMBs, sales and service-based businesses, healthcare and dental clinics, and real estate businesses. The long-term audience (professionals, freelancers, students, entrepreneurs, individuals) and the long-term vision (a Human Activity Operating System coordinating AI employees across connected applications) are recorded as future direction, not current scope.

2. System Overview

My Assistant is a multi-user SaaS workspace with a first-party web application, a first-party backend that owns agent orchestration, durable state, and integration execution, and a background worker that runs long-lived agent workflows. The current release implements the Lead Generation AI Employee; the remaining AI Employees (Customer Support, Content and SEO, Research, Personal Assistant, Business Operations) are catalogued as Planned capabilities and are visibly labelled as such wherever they appear.

Actors:

• Agency Owner / Operator — the primary current user; enters lead-generation tasks, reviews results, approves outreach, monitors progress and outcomes.
• Sales / Outreach Reviewer — reviews drafted personalized outreach and lead records and decides which external communications to authorize.
• System / background worker — executes agent workflows, integration calls, logging, and status transitions; not a human persona.
• External providers — authorized data sources, email/spreadsheet/calendar/CRM/automation integrations, and the AI model provider; owned by their respective providers, invoked only through authorized integrations.

Current behavior is bounded by hard constraints: only the Lead Generation AI Employee is built now; other agents are progressive capabilities, not day-one features; no static mockup or simulated action may be presented as a working integration; and the system must never claim a lead was verified, a message was sent, or a task was completed unless the system confirms it.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. The product is delivered as a first-party web application with a first-party backend and background worker. The anonymous Landing page and the Login surface are first-party and reachable without an established identity; every other destination is protected and requires an authenticated session. Identity is application-owned: the Agency Owner / Operator self-enrolls on the Login surface, and returning users verify their identity there before any protected workspace state (leads, workflows, approvals, logs, integrations) becomes available. The Login surface owns both first-use enrollment and returning verification; it does not own any workspace capability.

Provider and external ownership. Authorized data sources, email/spreadsheet/calendar/CRM/automation tools, and the AI model provider are external systems owned by their providers. My Assistant never reimplements them; it configures, invokes, and reports on them. Approved outreach executes only through an authorized integration that has been configured with protected credentials.

Current vs. future boundary. Current: the Landing and Login surfaces, the ten source-named workspace destinations, the Lead Generation AI Employee end-to-end workflow, durable storage, execution logs, the approval center, notifications and progress tracking, and integration management. Future (explicitly not current): the Customer Support, Content and SEO, Research, Personal Assistant, and Business Operations agents; organization accounts and scalable multi-tenant SaaS expansion; and the full HumanOS vision. Every surface that references a future capability must label it Planned inline.

Honesty boundary. Status is a first-class product fact. Every workflow displays exactly one of Pending, In Progress, Awaiting Approval, Completed, or Failed, derived from confirmed system events. No surface may render "Verified" or "Sent" without a corresponding confirmed system event.

2b. Source Content Inventory

Not applicable — no reference directive in this request declares a content_source.

2c. Page Content and Component Coverage

Landing

• Information / state: Anonymous public entry. Product name "My Assistant", tagline "Your AI Employees. One Intelligent Platform.", a plain statement that this is an AI-employee SaaS workspace, who it is for (digital marketing and SEO agencies first, then startups/SMBs, sales and service businesses, healthcare and dental clinics, real estate), and what it does (research, plan, organize, automate, use authorized tools, deliver verifiable results with approval). A live status strip demonstrating one agent capsule progressing through Pending → In Progress → Awaiting Approval → Completed.
• Primary action: One gold capsule CTA ("Start the Lead Gen agent") leading to the Login surface. Supporting actions: secondary link to sign in for returning users; anchor links to capability sections.
• Domain entities: AI Employee (Lead Generation, plus Planned agents), workflow status vocabulary, target-customer segments.
• Component responsibilities: full-bleed dark hero stage with the continuous pearl parametric surface bleeding off the top-right; oversized left-aligned Jost headline over a champagne hairline rule; capability sections separated by curved SVG boundaries; agent capsule with self-drawing status arc; inline Planned tags on non-current agents.
• States: loading — hero surface and status strip render from static CSS/SVG, no data fetch required; empty — not applicable (static marketing content); success — CTA navigates to Login; error — if the status strip's demonstration data cannot load, it renders a static completed-state illustration rather than a broken or fabricated live claim; recovery — CTA remains functional regardless of decorative asset failure.

Login

• Information / state: Anonymous access surface owning both self-service enrollment and returning verification. Fields for email and password (enrollment additionally collects the minimum profile needed to bind the account to the agency operator). Clear statement that protected workspace state is unavailable until identity is established.
• Primary action: Create account (first use) or Sign in (returning). Supporting actions: switch between enrollment and sign-in modes; surface validation and credential errors.
• Domain entities: User account, session.
• Component responsibilities: form with inline validation, submit control, mode toggle, error region, and post-success redirect into the protected workspace.
• States: loading — submit disabled with progress indication during credential verification; empty — pristine form with no errors; success — session established, redirect to Dashboard; error — invalid credentials, duplicate enrollment email, or weak/invalid input shown inline without revealing whether an account exists beyond what the source permits; recovery — user can correct input and resubmit; a failed enrollment leaves no partial account.

Dashboard

• Information / state: Active agents, ongoing tasks, completed workflows, pending approvals, recent activity, and integration health. Each workflow row shows exactly one status from Pending, In Progress, Awaiting Approval, Completed, Failed.
• Primary action: Open a workflow or task to inspect it. Supporting actions: jump to Approvals when pending approvals exist; jump to Integrations when integration health is degraded; start a new task via Chat.
• Domain entities: AI Employee, Workflow, Task, Approval, Activity event, Integration connection.
• Component responsibilities: agent capsule row with curved status arcs; ongoing/completed workflow tiles; pending-approval count tile; recent-activity ledger with tabular numerals and monospace-feeling timestamps; integration-health panel; curved section boundaries between bands.
• States: loading — skeleton pearl slabs in place of tiles; empty — first-run state explaining that no workflows exist yet and pointing to Chat to start the Lead Gen agent; success — all tiles populated from confirmed events; error — a failed tile shows a red-grey Failed state that does not animate, with a link to Activity History for the error report; recovery — retry control per failed panel; integration-health degradation links to Integrations.

AI Employees

• Information / state: The catalogue of specialized AI Employees — Lead Generation and Sales (current), Customer Support, Content and SEO, Research, Personal Assistant, Business Operations (Planned) — each with its capability list exactly as specified in the source.
• Primary action: Open the Lead Generation agent to start or inspect its work. Supporting actions: read capability detail per agent; filter by implemented vs. planned.
• Domain entities: AI Employee, capability, implementation status.
• Component responsibilities: diagonal cascade of capsule agent cards (not a uniform grid); curved status arc per capsule; champagne fill for the active agent and cyan for telemetry; inline Planned tag on non-current agents; capability list per card.
• States: loading — capsule placeholders; empty — not applicable (catalogue is static and always populated); success — all six agents listed with correct implementation labels; error — if capability metadata fails to load, cards render name and implementation status only, never invented capability text; recovery — retry control.

Tasks and Workflows

• Information / state: Workflow progress, final results, and accurate status (Pending, In Progress, Awaiting Approval, Completed, Failed) for every workflow, including the nine-step MVP lead-generation workflow and its per-step progress.
• Primary action: Inspect a workflow's steps and results. Supporting actions: open the associated approval when status is Awaiting Approval; open the resulting leads; open the error report when status is Failed.
• Domain entities: Workflow, Workflow step, Task, Status, Result, Error report.
• Component responsibilities: ruled status ledger with tabular numerals and a monospace-feeling timestamp column; per-step progress list; status arc that draws as the workflow advances; red-grey non-animating Failed state; links into Leads, Approvals, and Activity History.
• States: loading — ruled skeleton rows; empty — no workflows yet, with a pointer to Chat; success — statuses reflect confirmed events only; error — a workflow that cannot be read shows an explicit unavailable state rather than a stale status; recovery — retry, plus a link to Activity History for the recorded failure.

Chat

• Information / state: The natural-language task entry surface where the user types a request such as "Find 20 potential dental clinic clients in Chennai." Shows the AI's interpretation of the request and the criteria it identified before work proceeds.
• Primary action: Submit a task in natural language. Supporting actions: review and correct the interpreted criteria; confirm to start the workflow; open the resulting workflow.
• Domain entities: Conversation, Task request, Interpreted criteria, Workflow.
• Component responsibilities: message thread; interpretation panel showing identified criteria (e.g. count, industry, location) for user confirmation; submit control; link to the created workflow.
• States: loading — interpretation in progress indicator; empty — first-run prompt with an example request; success — interpretation shown, workflow created with status Pending; error — if interpretation fails, the raw request is preserved and the user is told the request could not be interpreted, with no workflow created; recovery — user edits and resubmits without losing the original text.

Leads

• Information / state: Stored, validated, deduplicated, and structured lead records produced by the Lead Generation agent, including collected publicly available business information, qualification against user-defined criteria, duplicate detection results, follow-up tracking, and lead-generation reporting. Each record shows its source link.
• Primary action: Review a lead record and its source. Supporting actions: filter and sort the ruled table; open the right-hand approval drawer for drafted outreach; export/save results to the configured database or connected spreadsheet; view follow-up status and results.
• Domain entities: Lead, Business information field, Qualification criterion, Duplicate record, Source reference, Follow-up, Report.
• Component responsibilities: ruled table with champagne row-hover and sharp corners; tabular numerals for counts and totals; source-link column; right-hand approval drawer; empty and error regions.
• States: loading — ruled skeleton rows; empty — no leads yet, with a pointer to Chat to run the Lead Gen agent; success — records shown with confirmed source links and qualification results; error — a record whose source cannot be resolved shows an explicit unresolved-source state rather than a fabricated value; recovery — retry per record and a link to Activity History.

Knowledge Base

• Information / state: The business knowledge base and uploaded documents used by agents, with each document's processing state.
• Primary action: Upload a document. Supporting actions: list, inspect, and remove documents; view processing status.
• Domain entities: Document, Upload, Processing state.
• Component responsibilities: upload control with validation feedback; document list; per-document status; empty and error regions.
• States: loading — list skeleton; empty — no documents yet, with an explanation of what the knowledge base is used for; success — document listed with confirmed processing state; error — unsupported type, oversized file, or failed processing shown explicitly with the reason; recovery — re-upload or remove the failed document.

Integrations

• Information / state: Connected and available email, spreadsheet, calendar, CRM, and automation tools, each with connection health and the credentials status (never the credential values).
• Primary action: Connect an integration. Supporting actions: disconnect; re-authorize a degraded connection; view health and last-successful-use.
• Domain entities: Integration connection, Provider, Health state, Credential reference.
• Component responsibilities: connection cards with health indicators; connect/disconnect controls; credential-status display that never renders secret values; error regions.
• States: loading — card skeletons; empty — no integrations connected, with an explanation that approved outreach cannot execute until an authorized integration is configured; success — connection healthy with confirmed last-use; error — failed authorization or degraded health shown explicitly with the provider's reason; recovery — re-authorize or reconnect.

Activity History

• Information / state: Task history, execution logs, error reports, and recorded results and completion status for every agent action, including the important agent actions required for audit.
• Primary action: Inspect an activity entry and its log detail. Supporting actions: filter by workflow, agent, status, or time; open the related workflow or lead; read the error report for a Failed entry.
• Domain entities: Activity event, Execution log entry, Error report, Result, Completion status.
• Component responsibilities: ruled log ledger with tabular numerals and monospace-feeling timestamps; red-grey non-animating Failed rows; detail panel; filter controls.
• States: loading — ruled skeleton rows; empty — no activity yet; success — entries reflect confirmed events only; error — an unreadable log range shows an explicit unavailable state; recovery — retry and narrow the filter range.

Approvals

• Information / state: Drafted personalized outreach messages and the lead records they target, awaiting authorization before any external communication is sent. Each item shows the workflow it belongs to and its Awaiting Approval status.
• Primary action: Approve and send an approved item. Supporting actions: hold (withhold) an item; inspect the drafted message as a real email artifact; inspect the target lead and its source.
• Domain entities: Approval request, Drafted outreach message, Target lead, Decision, Execution result.
• Component responsibilities: right-hand drawer that slides over the workspace; drafted outreach rendered as a real email artifact; champagne "Approve & send" control and hairline "Hold" control; per-item status that updates only on confirmed execution.
• States: loading — drawer skeleton; empty — no approvals pending, with an explanation that outreach is drafted by the Lead Gen agent and appears here for authorization; success — approved item executes through the authorized integration and its status reflects the confirmed result; error — if the integration fails, the item shows Failed with the provider's reason and is not marked sent; recovery — retry execution or return the item to held.

Settings

• Information / state: User settings, access permissions, and integration management entry points.
• Primary action: Update user settings. Supporting actions: review access permissions; navigate to Integrations for connection management.
• Domain entities: User settings, Access permission, Integration reference.
• Component responsibilities: settings form with validation; permission display; link into Integrations; error regions.
• States: loading — form skeleton; empty — defaults shown for a new account; success — saved settings confirmed; error — invalid input or save failure shown inline; recovery — correct and resave without losing entered values.

3. Functional Requirements

Each requirement is a distinct story point with provenance (explicit, basic_default, required_inference), lifecycle facts, and observable acceptance.

Identity and Access

FR-1 — Anonymous product entry (required_inference) As an anonymous visitor, I should reach a Landing page that explains that My Assistant is an AI-employee SaaS workspace, who it is for, and what it does, so that I can decide whether to start.

• Trigger: navigation to the application root without a session.
• Observable result: Landing renders product name, tagline, audience, and capability summary; protected workspace state is not reachable.
• Access state: anonymous.
• Failure/recovery: if decorative assets fail, the page still renders readable content and a working CTA.
• Continuation: CTA leads to the Login surface.

FR-2 — Self-service enrollment (required_inference) As an Agency Owner / Operator, I should create a first-party account on the Login surface, so that I can own durable workspace state.

• Trigger: submitting the enrollment form with valid input.
• Observable result: an account is created and a session is established; no partial account exists on failure.
• Access state: anonymous → authenticated.
• Failure/recovery: duplicate email, weak input, or server failure shown inline; the user can correct and resubmit.
• Continuation: redirect into the protected workspace.

FR-3 — Returning verification (required_inference) As a returning user, I should verify my identity on the Login surface, so that my protected workspace state becomes available.

• Trigger: submitting valid credentials.
• Observable result: session established; protected destinations become reachable.
• Access state: anonymous → authenticated.
• Failure/recovery: invalid credentials shown inline without exposing protected state; retry permitted.
• Continuation: redirect into the protected workspace.

FR-4 — Protected workspace access (explicit) As an authenticated user, I should be required to hold a session before any protected destination (Dashboard, AI Employees, Tasks and Workflows, Chat, Leads, Knowledge Base, Integrations, Activity History, Approvals, Settings) is available, so that my leads, workflows, approvals, and logs remain private.

• Trigger: navigation to any protected destination.
• Observable result: authenticated users see the destination; unauthenticated users are routed to the Login surface.
• Access state: authenticated.
• Failure/recovery: an expired session routes to Login without losing the intended destination.
• Continuation: return to the intended destination after verification.

Lead Generation MVP Workflow

FR-5 — Natural-language task entry (explicit) As an Agency Owner / Operator, I should enter a lead-generation task in natural language on the Chat page (for example, "Find 20 potential dental clinic clients in Chennai"), so that I can delegate the work without configuring a form.

• Trigger: submitting a message in Chat.
• Observable result: the request is recorded and submitted for interpretation.
• Access state: authenticated.
• Failure/recovery: if submission fails, the typed text is preserved.
• Continuation: interpretation is shown for confirmation.

FR-6 — AI interpretation of the request and criteria (explicit) As an Agency Owner / Operator, I should see the AI's interpretation of my request and the criteria it identified, so that I can confirm the work matches my intent before it starts.

• Trigger: a submitted natural-language request.
• Observable result: identified criteria (for example count, industry, location) are displayed for confirmation; a workflow is created with status Pending only after confirmation.
• Access state: authenticated.
• Failure/recovery: if interpretation fails, no workflow is created and the user is told the request could not be interpreted.
• Continuation: user confirms to start the workflow, or edits and resubmits.

FR-7 — Authorized-source or user-dataset gathering (explicit) As an Agency Owner / Operator, I should have the application gather information from an authorized source or a user-provided dataset, so that lead data comes from permitted origins.

• Trigger: a confirmed workflow begins execution.
• Observable result: collected business information is attached to the workflow; the source of each record is retained.
• Access state: authenticated; the workflow runs in the background worker.
• Failure/recovery: an unavailable or unauthorized source fails the step explicitly and the workflow moves to Failed with an error report; no data is invented.
• Continuation: successful gathering proceeds to validation.

FR-8 — Validation, deduplication, and structuring (explicit) As an Agency Owner / Operator, I should have results validated, deduplicated, and structured, so that I receive clean, usable lead records.

• Trigger: gathered records available.
• Observable result: duplicate records are detected and removed; remaining records are structured with their fields and source references.
• Access state: authenticated; executed by the background worker.
• Failure/recovery: a validation failure marks the step Failed with the reason recorded; partial results are not presented as complete.
• Continuation: structured results proceed to storage.

FR-9 — Qualification against user-defined criteria (explicit) As an Agency Owner / Operator, I should have prospects qualified against the criteria I specified, so that the resulting list matches my targeting.

• Trigger: structured records available.
• Observable result: each record carries its qualification result against the confirmed criteria.
• Access state: authenticated.
• Failure/recovery: if criteria cannot be applied, the step fails explicitly rather than silently including unqualified records.
• Continuation: qualified records proceed to storage and display.

FR-10 — Storage in a database or connected spreadsheet (explicit) As an Agency Owner / Operator, I should have results stored in a database or a connected spreadsheet, so that the leads persist and are usable outside the session.

• Trigger: qualified, structured records available.
• Observable result: records are persisted and retrievable on the Leads page; when a spreadsheet integration is configured, records are written there as well.
• Access state: authenticated.
• Failure/recovery: a storage or integration write failure marks the step Failed with the provider's reason; the workflow is not reported as Completed.
• Continuation: stored records are available for review.

FR-11 — Progress and final results display (explicit) As an Agency Owner / Operator, I should see progress and final results in the interface, so that I know what the agent is doing and what it produced.

• Trigger: workflow execution.
• Observable result: Tasks and Workflows shows per-step progress and final results; the Dashboard reflects the workflow's current status.
• Access state: authenticated.
• Failure/recovery: an unreadable workflow shows an explicit unavailable state rather than a stale status.
• Continuation: the user reviews results on Leads.

FR-12 — Drafted personalized outreach (explicit) As an Agency Owner / Operator, I should have personalized outreach emails and messages drafted for the qualified leads, so that I can review them before anything is sent.

• Trigger: qualified leads available.
• Observable result: drafted messages appear as approval items with status Awaiting Approval.
• Access state: authenticated.
• Failure/recovery: if drafting fails, the workflow moves to Failed with the reason recorded; no message is presented as ready.
• Continuation: drafts await review in Approvals.

FR-13 — Approval before external communication (explicit) As a Sales / Outreach Reviewer, I should review drafted outreach and approve or hold each item before any external communication is sent, so that no consequential external action happens without authorization.

• Trigger: an approval item with status Awaiting Approval.
• Observable result: approving authorizes execution; holding withholds it; the decision is recorded.
• Access state: authenticated.
• Failure/recovery: a decision that cannot be recorded leaves the item in Awaiting Approval rather than silently proceeding.
• Continuation: approved items proceed to execution; held items remain available.

FR-14 — Execution of approved actions through an authorized integration (explicit) As a Sales / Outreach Reviewer, I should have approved actions execute through an authorized integration, so that outreach actually reaches the recipient through a real, configured channel.

• Trigger: an approved approval item and a healthy authorized integration.
• Observable result: the integration executes the send; the item's status updates only on the confirmed result.
• Access state: authenticated; requires a configured authorized integration.
• Failure/recovery: if no authorized integration is configured or the integration fails, the item shows Failed with the provider's reason and is never marked sent.
• Continuation: the confirmed result is recorded and visible.

FR-15 — Recording results, errors, and completion status (explicit) As an Agency Owner / Operator, I should have the system record results, errors, and completion status, so that I can verify what actually happened.

• Trigger: any workflow step or integration call completes or fails.
• Observable result: Activity History holds the execution log entries, error reports, results, and completion status; the workflow's status reflects confirmed events.
• Access state: authenticated.
• Failure/recovery: if logging itself fails, the workflow is not reported as Completed.
• Continuation: the user inspects the record in Activity History.

FR-16 — Follow-up tracking and reporting (explicit) As an Agency Owner / Operator, I should have follow-ups tracked and results reported, so that I can see the outcome of the outreach over time.

• Trigger: an executed outreach action.
• Observable result: the lead record shows its follow-up state and the workflow reports its results.
• Access state: authenticated.
• Failure/recovery: an unknown follow-up state is shown as unknown, never as a completed follow-up.
• Continuation: the user reviews the report on Leads.

Status, Honesty, and Safety

FR-17 — Accurate workflow status (explicit) As an Agency Owner / Operator, I should see every workflow display exactly one accurate status from Pending, In Progress, Awaiting Approval, Completed, or Failed, so that I always know the true state of the work.

• Trigger: any workflow state change.
• Observable result: the status shown matches the confirmed system event; Failed renders as a red-grey state that does not animate.
• Access state: authenticated.
• Failure/recovery: if status cannot be read, an explicit unavailable state is shown instead of a stale value.
• Continuation: the user acts on the true status.

FR-18 — No unconfirmed claims (explicit) As an Agency Owner / Operator, I should never see a claim that a lead was verified, a message was sent, or a task was completed unless the system confirms it, so that I can trust the platform's reporting.

• Trigger: any rendering of lead, message, or task state.
• Observable result: "Verified" and "Sent" appear only alongside a confirmed system event; otherwise the true state is shown.
• Access state: authenticated.
• Failure/recovery: absent confirmation, the state renders as unconfirmed.
• Continuation: the user can inspect Activity History for the underlying event.

FR-19 — No fabricated research results (explicit) As an Agency Owner / Operator, I should never be shown fabricated research results or claims that unperformed actions succeeded, so that decisions rest on real data.

• Trigger: any research or gathering step.
• Observable result: records carry their source references; unresolved sources are shown as unresolved.
• Access state: authenticated.
• Failure/recovery: a failed research step is reported as Failed, never backfilled with invented data.
• Continuation: the user retries or adjusts the request.

FR-20 — Graceful handling of failed integrations and incomplete tasks (explicit) As an Agency Owner / Operator, I should have failed integrations and incomplete tasks handled gracefully, so that a failure does not corrupt state or mislead me.

• Trigger: an integration error or an interrupted workflow.
• Observable result: the affected item shows Failed with the provider's reason; the workflow is not reported as Completed; partial results are labelled as partial.
• Access state: authenticated.
• Failure/recovery: retry is available; the error report is recorded in Activity History.
• Continuation: the user retries or escalates.

FR-21 — Escalation of uncertain or sensitive cases (explicit) As an Agency Owner / Operator, I should have uncertain or sensitive cases escalated appropriately, so that the system does not act on ambiguous or sensitive matters without human judgment.

• Trigger: an uncertain or sensitive condition during agent work.
• Observable result: the case is surfaced for human decision rather than auto-executed.
• Access state: authenticated.
• Failure/recovery: if escalation cannot be surfaced, the workflow halts rather than proceeding.
• Continuation: the human decides and the workflow continues or is closed.

FR-22 — Important agent actions are logged (explicit) As an Agency Owner / Operator, I should have logs of important agent actions kept, so that I can audit what the system did.

• Trigger: any important agent action.
• Observable result: an entry appears in Activity History with its timestamp and outcome.
• Access state: authenticated.
• Failure/recovery: a logging failure is itself surfaced and prevents a Completed claim.
• Continuation: the user reviews the log.

FR-23 — Credential and private-data protection (explicit) As an Agency Owner / Operator, I should have API keys, credentials, passwords, and private customer information protected and never exposed, so that my business and my customers' data stay safe.

• Trigger: any storage, display, or transmission of credentials or private data.
• Observable result: no surface renders secret values; credentials are stored protected and referenced, not displayed.
• Access state: authenticated; secrets never reach the client.
• Failure/recovery: a detected exposure is treated as a failure and surfaced, not silently ignored.
• Continuation: the user can re-authorize the affected integration.

FR-24 — Respect for permissions and access controls (explicit) As an Agency Owner / Operator, I should have user permissions and application access controls respected, so that only authorized users reach protected state.

• Trigger: any access to protected state.
• Observable result: access is granted only to authenticated, authorized users.
• Access state: authenticated.
• Failure/recovery: unauthorized access is denied and routed to Login.
• Continuation: the user verifies identity and retries.

FR-25 — Authorized integrations only (explicit) As an Agency Owner / Operator, I should have the system use only authorized integrations, so that no unauthorized channel is used on my behalf.

• Trigger: any external call.
• Observable result: external calls occur only through integrations the user has configured and authorized.
• Access state: authenticated.
• Failure/recovery: an unauthorized or unconfigured channel results in an explicit failure, not a silent fallback.
• Continuation: the user configures the integration on Integrations.

Workspace Capabilities

FR-26 — Dashboard overview (explicit) As an Agency Owner / Operator, I should see active agents, ongoing tasks, completed workflows, pending approvals, recent activity, and integration health on the Dashboard, so that I have one operational view.

• Trigger: opening the Dashboard.
• Observable result: each band is populated from confirmed state; pending approvals and degraded integration health are actionable.
• Access state: authenticated.
• Failure/recovery: a failed band shows an explicit error with a retry and a link to Activity History.
• Continuation: the user drills into the relevant destination.

FR-27 — AI Employees catalogue with honest labelling (explicit) As an Agency Owner / Operator, I should browse the specialized AI Employees and their capabilities, with implemented features clearly distinguished from planned features, so that I know what the platform can actually do today.

• Trigger: opening AI Employees.
• Observable result: Lead Generation and Sales is shown as current; Customer Support, Content and SEO, Research, Personal Assistant, and Business Operations are shown with an inline Planned tag.
• Access state: authenticated.
• Failure/recovery: if capability metadata fails to load, only name and implementation status render.
• Continuation: the user opens the current agent or reads planned capability detail.

FR-28 — Task and workflow management (explicit) As an Agency Owner / Operator, I should manage tasks and workflows, so that I can track and act on the work in flight.

• Trigger: opening Tasks and Workflows.
• Observable result: workflows are listed with accurate status and per-step progress; each links to its results, approval, or error report.
• Access state: authenticated.
• Failure/recovery: an unreadable workflow shows an explicit unavailable state.
• Continuation: the user opens the linked destination.

FR-29 — Business knowledge base and document uploads (explicit) As an Agency Owner / Operator, I should maintain a business knowledge base with document uploads, so that agents can use approved business knowledge.

• Trigger: uploading or managing a document on Knowledge Base.
• Observable result: the document is listed with its confirmed processing state.
• Access state: authenticated.
• Failure/recovery: unsupported type, oversized file, or failed processing is shown with the reason; the document can be removed or re-uploaded.
• Continuation: the document becomes available to agents.

FR-30 — Integration management (explicit) As an Agency Owner / Operator, I should connect and manage supported email, spreadsheet, calendar, CRM, and automation tools, so that approved actions can execute through authorized channels.

• Trigger: connecting, disconnecting, or re-authorizing on Integrations.
• Observable result: connection health and last-successful-use are shown; credential values are never displayed.
• Access state: authenticated.
• Failure/recovery: failed authorization or degraded health is shown with the provider's reason and a re-authorize control.
• Continuation: healthy connections enable approved execution.

FR-31 — Notifications and progress tracking (explicit) As an Agency Owner / Operator, I should receive notifications and progress tracking, so that I know when work advances or needs me.

• Trigger: a workflow state change, especially entry into Awaiting Approval or Failed.
• Observable result: the change is surfaced in the workspace and reflected in the relevant status displays.
• Access state: authenticated.
• Failure/recovery: if a notification cannot be delivered, the underlying status remains accurate and visible in the workspace.
• Continuation: the user acts on the notification.

FR-32 — User settings, access permissions, and integration management (explicit) As an Agency Owner / Operator, I should manage user settings, access permissions, and integration management from Settings, so that the workspace is configured to my business.

• Trigger: opening Settings.
• Observable result: settings save with confirmation; permissions are displayed; integration management is reachable.
• Access state: authenticated.
• Failure/recovery: invalid input or save failure is shown inline without losing entered values.
• Continuation: the user returns to work with the updated configuration.

FR-33 — Workflow automation and scheduling (explicit) As an Agency Owner / Operator, I should have workflow automation and scheduling available as a core capability of the unified workspace, so that repetitive work can run on a schedule.

• Trigger: a scheduled or automated workflow definition.
• Observable result: the workflow runs and reports its status through the same status vocabulary.
• Access state: authenticated.
• Failure/recovery: a scheduled run that fails is reported as Failed with its error report.
• Continuation: the user inspects the run in Tasks and Workflows.

Engineering and Delivery Constraints

FR-34 — Inspect the existing project before changing code (explicit) As the engineering team, I should inspect the existing project before changing any code — identifying the existing framework, programming languages, dependencies, database, authentication, API routes, and integrations; understanding the existing architecture and working features; identifying incomplete functionality and technical risks; and presenting a concise implementation plan — so that changes are grounded in the real codebase.

• Trigger: start of implementation work.
• Observable result: a concise implementation plan exists before code changes.
• Failure/recovery: if the inspection cannot be completed, implementation does not proceed on assumptions.
• Continuation: incremental, testable changes begin.

FR-35 — Preserve the existing stack and structure (explicit) As the engineering team, I should not rebuild the project from scratch, delete working features, or replace the existing technology stack without a clear reason, and I should preserve the existing code structure wherever practical, so that working functionality is not lost.

• Trigger: any implementation change.
• Observable result: existing working features remain; changes are incremental and testable.
• Failure/recovery: a change that would break working features is reverted or redesigned.
• Continuation: the change ships incrementally.

FR-36 — Modular, secure, maintainable implementation (explicit) As the engineering team, I should use modular architecture, secure API handling, authentication, input validation, reliable error handling, and maintainable code, and design for multiple users and agents without overengineering the initial MVP, so that the platform can grow without being overbuilt now.

• Trigger: any implementation work.
• Observable result: modules are separated by responsibility; APIs validate input and handle errors; authentication is enforced; the MVP is not over-engineered.
• Failure/recovery: a design that overbuilds the MVP is simplified.
• Continuation: the platform remains extensible for later phases.

FR-37 — Real integrations, not simulations (explicit) As the engineering team, I should test the entire MVP workflow with realistic examples and never treat a static mockup or simulated action as a working integration, so that the delivered workflow is genuinely functional.

• Trigger: verification of the MVP workflow.
• Observable result: the end-to-end workflow runs against real authorized sources and integrations with realistic examples.
• Failure/recovery: a simulated path is treated as a defect, not a passing test.
• Continuation: the workflow is verified end to end.

Future Requirements (Not Current Scope)

The following are explicitly future and must not appear as current pages, current acceptance criteria, or current capabilities. Where referenced in the current UI, they are labelled Planned.

• FUT-1 — Customer Support Agent: answer common questions using approved business knowledge; categorize and prioritize enquiries; draft responses and create support records; escalate complex issues to a human.
• FUT-2 — Content and SEO Agent: keyword and search-intent research; competitor and content-gap analysis; SEO content briefs and outlines; on-page and technical SEO audits; content calendars and SEO reports; improvement recommendations based on available data.
• FUT-3 — Research Agent: research companies, markets, competitors, and products; compare options and summarize findings; provide source references for important claims; create structured research reports.
• FUT-4 — Personal Assistant: organize tasks, goals, schedules, and reminders; summarize documents and conversations; prepare plans and prioritize activities.
• FUT-5 — Business Operations Agent: assist with spreadsheets, reports, documents, and records; automate repetitive administrative workflows; monitor tasks and report errors.
• FUT-6 — Phase 2: reliable integrations, persistent storage, execution logs, and approvals at production depth.
• FUT-7 — Phase 3: improved lead management, reporting, reusable workflows, and agency features.
• FUT-8 — Phase 4: Customer Support, Research, Content and SEO, and Personal Assistant agents.
• FUT-9 — Phase 5: expansion into a scalable SaaS platform with organization accounts.
• FUT-10 — Long-term vision: a Human Activity Operating System (HumanOS) that understands user goals, coordinates AI employees, connects applications, and helps users complete real-world tasks from one unified workspace.
• FUT-11 — Future audience: professionals, freelancers, students, entrepreneurs, and individuals.

4. User Personas

Agency Owner / Operator

Product context. Runs a digital marketing or SEO agency and is the primary user of the first MVP. They are handing real outreach and real prospect data to software, so they need the platform to feel engineered and controlled rather than experimental. They work in the workspace repeatedly across days, so their state — leads, workflows, approvals, logs — must persist and be resumable.

Primary goal. Delegate lead generation end to end and get a clean, qualified, deduplicated list of prospects with drafted outreach, without losing control over what actually leaves the building.

Distinct accepted responsibilities. Enters lead-generation tasks in natural language (for example, "Find 20 potential dental clinic clients in Chennai"); confirms the AI's interpretation and criteria; reviews the gathered, validated, deduplicated, and structured lead results; monitors progress, outcomes, errors, and completion status; configures integrations and the business knowledge base; manages settings and access permissions.

Relevant inputs and decisions. The natural-language request and its criteria; the choice of authorized source or user-provided dataset; the decision to confirm or correct the interpreted criteria; the decision to configure or re-authorize an integration; the decision to retry a failed workflow.

Interactions with other accepted participants. Hands drafted outreach to the Sales / Outreach Reviewer for authorization; receives the confirmed execution result back into the workflow and lead records. Interacts with external providers only through configured authorized integrations.

Observable success. A workflow reaches Completed with a stored, deduplicated, qualified lead list whose records carry source references; the Dashboard shows the completed workflow and healthy integrations; Activity History holds the execution log and any error reports.

Sales / Outreach Reviewer

Product context. Reviews drafted personalized outreach messages and lead records before any external communication is sent. Their work is a gate, not a pipeline: they exist to make sure nothing consequential leaves the building without a human decision, and they depend on the platform's honesty about what was actually executed.

Primary goal. Authorize the right outreach and withhold the wrong outreach, with confidence that an approved item was genuinely sent and a held item was genuinely not sent.

Distinct accepted responsibilities. Reviews drafted outreach as a real email artifact alongside its target lead and source; approves or holds each item; relies on accurate status (Pending, In Progress, Awaiting Approval, Completed, Failed) and recorded outcomes to confirm what was actually executed.

Relevant inputs and decisions. The drafted message content, the target lead record and its source reference, the workflow the item belongs to, and the integration health that determines whether execution can succeed.

Interactions with other accepted participants. Receives drafted outreach produced by the Agency Owner / Operator's workflow; their decision determines whether the background worker executes the send through the authorized integration; the confirmed result flows back to the workflow and lead records the Agency Owner / Operator monitors.

Observable success. Approved items show a confirmed execution result and are never marked sent without one; held items remain available and unexecuted; failed executions show the provider's reason and are not reported as sent.

5. Core User Flows

Flow 1 — Anonymous visitor learns about My Assistant and starts

1. An anonymous visitor navigates to the application root and lands on Landing.
2. The visitor reads the product name, tagline, audience, and capability summary, and sees the live status strip demonstrating one agent capsule progressing through Pending → In Progress → Awaiting Approval → Completed.
3. The visitor selects the gold capsule CTA ("Start the Lead Gen agent").
4. Observable result: the visitor arrives at the Login surface; no protected workspace state was reachable at any point.
5. Next step: the visitor enrolls (Flow 2) or signs in (Flow 3).

Flow 2 — Agency Owner / Operator enrolls and reaches the workspace

1. On Login, the Agency Owner / Operator selects the enrollment mode and submits valid account details.
2. Observable result: an account is created and a session is established; the user is redirected into the protected workspace.
3. Failure/recovery: if the email is already enrolled, the input is invalid, or the server fails, the error is shown inline and no partial account is created; the user corrects the input and resubmits.
4. Next step: the user lands on Dashboard and begins Flow 4.

Flow 3 — Returning user verifies identity

1. On Login, the returning user submits credentials.
2. Observable result: the session is established and protected destinations become reachable.
3. Failure/recovery: invalid credentials are shown inline without exposing protected state; the user retries. An expired session during later work routes back to Login without losing the intended destination.
4. Next step: the user returns to the intended destination.

Flow 4 — Agency Owner / Operator runs the Lead Generation MVP workflow end to end

1. The Agency Owner / Operator opens Chat and types a natural-language request, for example "Find 20 potential dental clinic clients in Chennai."
2. Observable result: the request is recorded and submitted for interpretation. Failure/recovery: if submission fails, the typed text is preserved.
3. The AI interprets the request and the Chat page displays the identified criteria (count, industry, location) for confirmation.
4. The user confirms the criteria. Observable result: a workflow is created with status Pending. Failure/recovery: if interpretation fails, no workflow is created and the user is told the request could not be interpreted; the user edits and resubmits without losing the original text.
5. The background worker gathers information from an authorized source or the user-provided dataset. Observable result: collected business information is attached to the workflow with its source retained; the workflow moves to In Progress. Failure/recovery: an unavailable or unauthorized source fails the step explicitly and the workflow moves to Failed with an error report; no data is invented.
6. The worker validates, deduplicates, and structures the results. Observable result: duplicate records are detected and removed; remaining records are structured with their fields and source references. Failure/recovery: a validation failure marks the step Failed with the reason recorded; partial results are not presented as complete.
7. The worker qualifies prospects against the confirmed criteria. Observable result: each record carries its qualification result. Failure/recovery: if criteria cannot be applied, the step fails explicitly rather than silently including unqualified records.

8. The worker stores the results in the database and, when configured, writes them to the connected spreadsheet. Observable result: records persist and are retrievable on Leads. Failure/recovery: a storage or integration write failure marks the step Failed with the provider's reason; the workflow is not reported as Completed.
9. The worker drafts personalized outreach emails and messages for the qualified leads. Observable result: drafts appear as approval items with status Awaiting Approval. Failure/recovery: if drafting fails, the workflow moves to Failed with the reason recorded; no message is presented as ready.
10. The Agency Owner / Operator opens Tasks and Workflows and sees per-step progress and the workflow's accurate status. Failure/recovery: an unreadable workflow shows an explicit unavailable state rather than a stale status.
11. The user opens Leads and reviews the stored, validated, deduplicated, qualified records with their source links. Failure/recovery: a record whose source cannot be resolved shows an explicit unresolved-source state rather than a fabricated value.
12. Next step: the user hands the drafted outreach to the Sales / Outreach Reviewer (Flow 5).

Flow 5 — Sales / Outreach Reviewer authorizes outreach

1. The Sales / Outreach Reviewer opens Approvals and sees the drafted outreach items with status Awaiting Approval, each showing the workflow it belongs to.
2. The reviewer opens an item; the right-hand drawer slides over the workspace and renders the drafted message as a real email artifact alongside its target lead and source.
3. The reviewer decides per item:
   • Approve & send (champagne control) authorizes execution.
   • Hold (hairline control) withholds it.
4. Observable result: the decision is recorded; approved items proceed to execution, held items remain available and unexecuted. Failure/recovery: a decision that cannot be recorded leaves the item in Awaiting Approval rather than silently proceeding.
5. The background worker executes the approved action through the authorized integration. Observable result: the item's status updates only on the confirmed result. Failure/recovery: if no authorized integration is configured or the integration fails, the item shows Failed with the provider's reason and is never marked sent; the reviewer can retry execution or return the item to held.
6. Next step: the confirmed result flows back to the workflow and lead records (Flow 6).

Flow 6 — Agency Owner / Operator verifies outcomes and recovers from failure

1. The Agency Owner / Operator opens Dashboard and sees active agents, ongoing tasks, completed workflows, pending approvals, recent activity, and integration health.
2. The user opens Activity History and inspects the execution log entries, error reports, results, and completion status for the workflow. Observable result: entries reflect confirmed events only; "Verified" and "Sent" appear only alongside a confirmed system event.
3. The user opens Leads and reviews follow-up tracking and the lead-generation report. Observable result: the lead record shows its follow-up state; an unknown follow-up state is shown as unknown, never as a completed follow-up.
4. Failure/recovery path: if a workflow shows Failed, the user opens its error report in Activity History, reads the provider's reason, and either retries the workflow or opens Integrations to re-authorize the degraded connection. Observable result: the red-grey Failed state does not animate and is never replaced by a Completed claim without a confirmed event.
5. Continuation: the user starts a new task in Chat or adjusts the criteria and reruns.

Flow 7 — Agency Owner / Operator configures integrations before outreach can execute

1. The Agency Owner / Operator opens Integrations and sees connected and available email, spreadsheet, calendar, CRM, and automation tools with their health.
2. The user connects an integration and completes the provider's authorization. Observable result: the connection shows healthy with a confirmed last-successful-use; credential values are never displayed.
3. Failure/recovery: failed authorization or degraded health is shown with the provider's reason and a re-authorize control; the user retries.
4. Continuation: with a healthy authorized integration configured, approved outreach in Flow 5 can execute externally. Without one, approved items fail explicitly rather than silently falling back to an unauthorized channel.

Flow 8 — Agency Owner / Operator maintains the business knowledge base

1. The Agency Owner / Operator opens Knowledge Base and uploads a document.
2. Observable result: the document is listed with its confirmed processing state.
3. Failure/recovery: an unsupported type, oversized file, or failed processing is shown with the reason; the user removes or re-uploads the document.
4. Continuation: the document becomes available to agents.

Flow 9 — Agency Owner / Operator reviews the AI Employees catalogue

1. The Agency Owner / Operator opens AI Employees and sees the diagonal cascade of capsule agent cards.
2. Observable result: Lead Generation and Sales is shown as current with its capability list; Customer Support, Content and SEO, Research, Personal Assistant, and Business Operations carry an inline Planned tag.
3. Failure/recovery: if capability metadata fails to load, cards render name and implementation status only — never invented capability text.
4. Continuation: the user opens the current agent to start or inspect its work, or reads planned capability detail without expecting it to be available.

Flow 10 — Agency Owner / Operator manages settings and permissions

1. The Agency Owner / Operator opens Settings and updates user settings.
2. Observable result: settings save with confirmation; access permissions are displayed; integration management is reachable.
3. Failure/recovery: invalid input or a save failure is shown inline without losing entered values; the user corrects and resaves.
4. Continuation: the user returns to work with the updated configuration.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. Muse: Zaha Hadid. Headline: Fluid parametric grandeur for a coordinated AI workforce.

Mode. Dark mode.

Colour tokens by role.

Usage rules: warm champagne gold (#C9A227) is the primary — used for the single active agent, approval actions, and the one gold CTA per screen; it is never used for body text, only for large labels and controls. Cool icy cyan (#7FD8E8) is the data/telemetry accent — status pulses, progress arcs, source links — and never for large fills. Muted silver (#8A929C) carries secondary labels and metadata. Text is near-white for AA contrast on the dark ground. Charcoal-pearl dark ground with slightly lifted pearl surfaces and hairline silver borders.

Typography.

• Headings: Jost, weight 200–300 for display; tracking -0.01em on huge sizes and +0.16em on uppercase micro-labels. Headlines are sentence case at 56–128px; eyebrows are uppercase 11px with wide letterspacing.
• Body: Outfit, weight 300/400 at 16–18px with 1.7 line-height for calm reading inside dense dashboards.
• Scale: 1.333 modular — 128 / 96 / 72 / 56 / 40 / 28 / 20 / 16 / 13. Mobile display 56px to desktop 128px via clamp().
• Tabular numerals for all counts, lead totals, and timestamps.

Shape language. Continuous parametric curves: 40–64px radii on hero panels, asymmetric curved section boundaries that sweep across the page, and capsule controls. Cards are pearl slabs with one flowing corner, never identical boxes. Hairline silver rules and arc segments (SVG) act as flow lines connecting agent tiles. Sharp corners are reserved for data tables and log rows so the interface reads as engineered, not soft.

Spacing rhythm. 12-column architectural grid with dramatic negative space. The dashboard shell is a fixed left rail (icons + labels at 1280px, icon-only at 768px, bottom tab bar at 375px) with the workspace flowing right. Sections are separated by curved SVG boundaries rather than straight dividers. Everything reflows to a single column at 375px with all labels, numbers, and controls whole inside the viewport.

Imagery style. Architectural and generative rather than photographic: luminous pearl-and-silver parametric surfaces rendered as SVG/CSS gradients, thin arc diagrams, topographic flow lines, and small monochrome agent sigils. Lead and company data is shown as real tabular records with source links — never as fake logos or stock people. One crafted hero form (a continuous looping surface built from layered gradients and arcs) stands in for the "one coordinated workforce."

Explicitly avoided. A centred headline + subtext + blue button hero, or any gradient-blob background; uniform grids of identical hover-lift cards; indigo/violet/blue as primary or accent on a white ground; bootstrap-blue status colours; Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, or system-ui for headings or body; photographic stock people, fake company logos, or fabricated lead counts presented as verified; bouncy or springy micro-interactions, particle fields, or WebGL scenes beyond the one crafted hero surface; sharp-cornered default admin chrome with no curved boundaries or flow lines; any status shown as "Verified" or "Sent" without a confirmed system event.

7. Signature Design Concept

The Continuous Surface. The public entry is a full-bleed dark stage (#0B0D10) in which a single sweeping pearl-and-silver parametric surface — built from layered CSS gradients and SVG arcs, not a blob — occupies the right 60% of the viewport and bleeds off the top-right edge, catching a cold cyan rim light along its curve. On the left, an oversized Jost 200 headline ("Your AI Employees. One Intelligent Platform.") runs 56px on mobile to 128px on desktop, stacked over a champagne-gold hairline rule, with the tagline and one gold capsule CTA ("Start the Lead Gen agent") pinned beneath it — left-aligned, never centred. A thin live status strip along the bottom edge shows one agent capsule progressing through its states, so the hero itself demonstrates the product's honest-status principle.

The concept recomposes only accepted content and controls: the product name, tagline, audience and capability summary, the single CTA into the Login surface, and the status vocabulary (Pending, In Progress, Awaiting Approval, Completed, Failed). It introduces no new behaviour, page, or destination. The same continuous-surface language carries into the workspace through curved section boundaries, capsule agent cards with self-drawing status arcs, and the ruled status ledger whose sharp corners deliberately contrast with the flowing form — the muse's own contrast between flowing form and precise plan.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: layered_2d

Landing Hero Motion Brief.

• Focal subject. The single continuous pearl-and-silver parametric surface occupying the right 60% of the viewport, bleeding off the top-right edge with a cold cyan rim light along its curve.
• Input → transformation → outcome thesis. As the visitor arrives, the surface's layered gradients and SVG arcs resolve into place and the cyan rim light traces the curve; the bottom status strip's agent capsule then draws its status arc from Pending through In Progress and Awaiting Approval to Completed. The transformation demonstrates the product's defining promise — a coordinated AI workforce that reports its true state — using only accepted status vocabulary and no fabricated data.
• Motion vocabulary. 600–900ms cubic-bezier(0.22,1,0.36,1) sweeps for section entrances; a slow 20s ambient drift on the hero's curved forms; scroll-linked parallax between the silver flow lines and the hero surface; status changes animate as an arc drawing around the agent capsule; failures snap to a red-grey state instantly with no bounce.
• Composed first frame. Dark stage, left-aligned oversized Jost headline over a champagne hairline rule, tagline and one gold capsule CTA beneath it, the pearl surface holding the right 60% and bleeding off the top-right, and the status strip along the bottom edge with the capsule at its first state.
• Reduced-motion state. All motion collapses to instant static states: the surface renders fully resolved, the status strip shows a static completed-state illustration, and no parallax or ambient drift occurs. The headline, tagline, CTA, and status strip remain fully readable and operable.

9. Non-Functional Requirements

NFR-1 — Authentication and session continuity (explicit) The product requires authentication and is designed for multiple users. Protected destinations are reachable only with an established session; the Login surface owns both self-service enrollment and returning verification. Rationale: the source requires authentication and multiple users, and the operator creates durable application-owned state that must remain bound to the correct participant.

NFR-2 — Credential and secret protection (explicit) API keys, credentials, and passwords are stored protected and never exposed to the client or rendered on any surface; private customer information is never exposed. Rationale: explicit safety requirement.

NFR-3 — Input validation and reliable error handling (explicit) All API handling validates input and handles errors reliably; failures are surfaced explicitly rather than silently swallowed. Rationale: explicit technical requirement.

NFR-4 — Modular, maintainable architecture (explicit) The implementation uses modular architecture and maintainable code, designed for multiple users and agents without overengineering the initial MVP. Rationale: explicit technical requirement.

NFR-5 — Honest status and no fabricated claims (explicit) Every workflow displays exactly one accurate status from Pending, In Progress, Awaiting Approval, Completed, or Failed, derived from confirmed system events. The system never claims a lead was verified, a message was sent, or a task was completed unless the system confirms it, and never fabricates research results or claims unperformed actions succeeded. Rationale: explicit safety and reliability requirement.

NFR-6 — Audit logging (explicit) Logs of important agent actions are kept and are inspectable in Activity History. Rationale: explicit safety requirement.

NFR-7 — Graceful failure and escalation (explicit) Failed integrations and incomplete tasks are handled gracefully; uncertain or sensitive cases are escalated appropriately rather than auto-executed. Rationale: explicit safety requirement.

NFR-8 — Real integrations only (explicit) The MVP workflow is tested with realistic examples; a static mockup or simulated action is never treated as a working integration. Rationale: explicit hard constraint.

NFR-9 — Implemented vs. planned labelling (explicit) Implemented features are clearly distinguished from planned features wherever they appear. Rationale: explicit requirement.

NFR-10 — Responsive, readable interface (explicit) Readable typography, responsive layouts, consistent components, intuitive navigation, clear status indicators, and helpful empty and error states. Headlines, wordmarks, labels, numbers, cards' text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit, with no other element covering them. Rationale: explicit UI requirement plus the creative direction's readability rule.

NFR-11 — Durable state and background execution (required_inference) Workflows, leads, approvals, logs, and integration connections persist across sessions, and long-running agent work executes in a background worker so the interface remains responsive and progress is observable. Rationale: indispensable mechanics for the accepted end-to-end workflow, which spans gathering, validation, drafting, human approval, and external execution across separate moments in time.

NFR-12 — Access control (explicit) User permissions and application access controls are respected; only authorized integrations are used. Rationale: explicit safety requirement.

NFR-13 — Incremental, non-destructive change (explicit) The existing project is inspected before any code change; the project is not rebuilt from scratch, working features are not deleted, and the existing technology stack is not replaced without a clear reason; existing code structure is preserved wherever practical and changes are incremental and testable. Rationale: explicit hard constraint.

NFR-14 — Reduced-motion support (basic_default) All motion collapses to instant static states under prefers-reduced-motion, with a usable static arrangement in which every item can be brought fully into view. Rationale: accessibility default consistent with the creative direction.

10. Tech Stack

The source does not name a specific framework, language, or database; it requires that the existing project be inspected first and that the existing technology stack not be replaced without a clear reason. The following is therefore the working stack for this build, chosen to satisfy the explicit requirements for authentication, secure API handling, input validation, reliable error handling, modular architecture, durable state, background execution, and real integrations.

• Frontend: React (web application), with the dark-mode design system described in Section 6.
• Backend: Python / FastAPI, extended with routes and modules for the agent orchestration, lead, workflow, approval, integration, and logging domains. One shared backend process serves the application API.
• Background worker: a separate process for long-running agent workflows (gathering, validation, drafting, and approved external execution), so the interface stays responsive and progress is observable. This is the one workflow that genuinely requires its own process.
• Storage: a relational database for durable application-owned state (users, workflows, workflow steps, leads, approvals, activity logs, integration connections, knowledge-base documents). Redis for queueing and short-lived workflow/progress state, consistent with the background-execution requirement.
• AI: an AI model provider invoked server-side for request interpretation, criteria extraction, and outreach drafting. Provider credentials are held server-side and never exposed to the client.
• Integrations: authorized email, spreadsheet, calendar, CRM, and automation tools, connected through provider authorization and invoked only through configured, authorized connections.
• Deployment: Docker and docker-compose for the application, backend, worker, database, and Redis. Kubernetes is not required for the current MVP.

11. Assumptions and Constraints

Assumptions.

• A1 — The existing project is inspected before any code change, and its framework, languages, dependencies, database, authentication, API routes, and integrations are identified and documented in a concise implementation plan. (explicit)
• A2 — Where the existing stack already satisfies a requirement, it is preserved rather than replaced. (explicit)
• A3 — The AI model provider is an external service invoked server-side; its credentials are configured as protected secrets. (required_inference)
• A4 — Authorized data sources and outreach channels are external providers reached only through configured integrations; the platform does not reimplement them. (explicit)
• A5 — The MVP is scoped to the Lead Generation AI Employee for digital marketing agencies; other agents are catalogued and labelled Planned. (explicit)
• A6 — The two accepted personas are the closed active-human set for this generation. (required_inference)

Constraints.

• C1 — Do not build every agent simultaneously; start with the Lead Generation AI Employee for digital marketing agencies. (explicit)
• C2 — Treat the listed AI Employees as product capabilities to implement progressively, not features automatically available from day one. (explicit)
• C3 — Do not treat a static mockup or simulated action as a working integration. (explicit)
• C4 — Never claim that a lead was verified, a message was sent, or a task was completed unless the system confirms it. (explicit)
• C5 — Never fabricate research results or claim unperformed actions succeeded. (explicit)
• C6 — Obtain approval before consequential external actions when required; request approval before sending external communications. (explicit)
• C7 — Never expose passwords, API keys, or private customer information; protect API keys and credentials. (explicit)
• C8 — Respect user permissions and application access controls; use authorized integrations and appropriate access controls. (explicit)
• C9 — Inspect the existing project before changing any code. (explicit)
• C10 — Do not rebuild the project from scratch, delete working features, or replace the existing technology stack without a clear reason. (explicit)
• C11 — Preserve the existing code structure wherever practical; make incremental, testable changes. (explicit)
• C12 — Design for multiple users and agents without overengineering the initial MVP. (explicit)
• C13 — Clearly distinguish implemented features from planned features. (explicit)
• C14 — Avoid unnecessary complexity. (explicit)

12. Glossary

• AI Employee — a specialized AI agent in the platform (Lead Generation and Sales, Customer Support, Content and SEO, Research, Personal Assistant, Business Operations). Only the Lead Generation and Sales agent is current; the rest are Planned.
• Agency Owner / Operator — the primary current user; runs a digital marketing or SEO agency and drives the lead-generation workflow.
• Sales / Outreach Reviewer — the user who reviews drafted outreach and authorizes or withholds external communication.
• Approval — a pending authorization for a consequential external action, specifically drafted outreach awaiting a decision before sending.
• Approval center — the Approvals destination where drafted outreach is reviewed and approved or held.
• Authorized integration — an external email, spreadsheet, calendar, CRM, or automation tool that the user has connected and authorized; the only channel through which external actions execute.
• Authorized source — a data source the user is permitted to use for gathering business information.
• Awaiting Approval — the workflow status indicating work has paused for a human authorization decision.
• Completed — the workflow status indicating the work finished with a confirmed system event.
• Failed — the workflow status indicating the work did not complete; rendered as a red-grey state that does not animate.
• HumanOS (Human Activity Operating System) — the long-term vision of a system that understands user goals, coordinates AI employees, connects applications, and helps users complete real-world tasks from one unified workspace. Future, not current scope.
• In Progress — the workflow status indicating the work is actively executing.

• Lead — a stored, validated, deduplicated, structured prospect record produced by the Lead Generation agent, carrying its collected business information, qualification result, source reference, and follow-up state.
• Lead Generation and Sales Agent — the first MVP AI Employee; researches potential customers, collects and organizes publicly available business information, qualifies leads against user-defined criteria, detects duplicates, drafts personalized outreach, saves leads, tracks follow-ups, reports results, and requests approval before sending external communications.
• Pending — the workflow status indicating the work is created and not yet started.
• Planned — an inline label marking a capability that is catalogued but not available in the current release.
• Workflow — a unit of agent work with a defined status, per-step progress, results, and error reports.
• Workflow status — exactly one of Pending, In Progress, Awaiting Approval, Completed, or Failed, derived from confirmed system events.