growqr-app/growqr-backend
3
0
Fork 0
Code Issues 2 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

PRD for GrowQr Ai Agent System #1

New Issue
Open
opened 2026-05-15 15:35:26 +00:00 by Sai-karthik · 0 comments
Sai-karthik commented 2026-05-15 15:35:26 +00:00
Owner
Copy Link

Grow Agent Platform PRD

1. Overview

GrowQR is a multi-agent development and personal growth platform where every user gets a dedicated master agent called a Grow Agent. The Grow Agent owns the user's long-running context, memory, workflows, files, repositories, execution state, and progress.

The platform combines:

  • A Slack-like frontend for chat, progress, and sub-agent channels.
  • A dedicated Grow Agent per user.
  • Multiple specialized sub-agents per Grow Agent.
  • Git-backed memory and state using per-user repositories.
  • OpenCode-backed coding and execution environments.
  • Rivet Kit actors for durable state, orchestration, and actions.
  • Gitea for internal Git hosting and repository management.
  • Backend APIs for auth, actor registry, OpenCode server management, payments, and product flows.

2. Product Goals

  • Give every user a persistent AI workspace that can remember, plan, execute, and evolve over time.
  • Store all user agent state in Git so memory, files, decisions, and workflow history are inspectable and versioned.
  • Let a master Grow Agent orchestrate specialized sub-agents.
  • Give each sub-agent isolated execution scope, logs, state, and optionally a Slack-style channel.
  • Provide a frontend where users can talk to the Grow Agent, watch sub-agent progress, and trigger structured quests or pathways.
  • Support paid access where payment provisions and starts the user's Grow Agent environment.

3. Core Concepts

3.1 User

A user is the primary account holder. Each user has:

  • One active Grow Agent.
  • One Lifelong Git repository for agent memory and workspace files.
  • Access to a dedicated OpenCode execution environment.(Agent)
  • Access to a Slack-like UI with channels for master and sub-agent activity.

3.2 Grow Agent

The Grow Agent is the user's master agent and orchestration layer.

Responsibilities:

  • Maintain user-level memory and context.
  • Decide which sub-agent should handle a task.
  • Trigger sub-agent workflows.
  • Track progress and state transitions.
  • Commit important state changes to the user's Git repo.
  • Coordinate OpenCode sessions for code execution.
  • Expose status to the frontend.

The Grow Agent should be implemented as a durable actor, likely with Rivet Kit.

3.3 Sub-Agents

Sub-agents are specialized workers owned by a Grow Agent.

Examples:

  • Coding agent using OpenCode.
  • Repo setup agent using Gitea APIs.
  • Migration agent.
  • Product flow agent.
  • Payment/onboarding agent.
  • Quest/pathway agent.
  • Backend CRUD agent.
  • Frontend planning agent.

Each sub-agent should have:

  • A unique actor identity.
  • A bounded workspace directory.
  • A bounded set of capabilities.
  • A dedicated state object.
  • A channel/thread in the frontend.
  • Optional backing microservice integration.

3.4 Git-Backed State

Every user gets a Git repository that stores:

  • Agent memory files.
  • User goals and profile context.
  • Quest/pathway progress.
  • Plans, summaries, decisions, and task history.
  • Generated code/files.
  • Sub-agent outputs.
  • System state snapshots where appropriate.

Gitea should be used as the internal Git server.

Repository model:

  • One primary repo per user for Grow Agent memory and workspace state.
  • Optional child repos for generated products or user projects (for the workflows).
  • All writes from agents go through controlled Git actions.
  • Important state mutations should produce commits with structured messages.

3.5 OpenCode Execution

OpenCode is used as the code execution and coding-agent interface.

Expected model:

  • Each user gets access to an OpenCode server or OpenCode workspace.
  • OpenCode runs with strict directory boundaries.
  • The Grow Agent can create sessions, send prompts, inspect results, and receive progress.
  • Coding sub-agents use OpenCode to edit code, run commands, and report status.
  • one OpenCode container per actor

4. System Architecture

4.1 High-Level Components

  • Frontend app: Slack-like UI, chat interface, quests/pathways, progress views.
  • Backend API: auth, billing, user management, actor registry, OpenCode management, Gitea management.
  • Rivet Kit actor runtime: durable Grow Agent and sub-agent actors.
  • Gitea: internal Git hosting for per-user repos.
  • OpenCode server: coding and command execution environment.
  • Database: relational app data such as users, auth, billing, actor registry metadata, and repo mappings.
  • Queue/event layer: optional event delivery between backend, actors, OpenCode, and frontend.

4.2 Request Flow

  1. User signs up or logs in.
  2. Payment or plan check confirms entitlement.
  3. Backend provisions the user's Grow Agent.
  4. Backend creates or links the user's Gitea repo.
  5. Backend creates or links the user's OpenCode workspace/server.
  6. User sends a message in the frontend.
  7. Message is routed to the user's Grow Agent actor.
  8. Grow Agent updates state, decides whether to call sub-agents, and commits durable context to Git when needed.
  9. Sub-agents run tasks using bounded tools, microservices, Git actions, or OpenCode.
  10. Progress events stream back to the frontend.

5. Backend Requirements

5.1 Auth

The backend must support:

  • User registration and login.
  • using clerk
  • Per-user authorization checks for all actor, repo, and OpenCode resources.
  • Service-to-service auth for actors calling backend APIs.

5.2 Actor Registry API

The backend needs an actor registry that tracks:

  • User ID.
  • Grow Agent actor ID.
  • Sub-agent actor IDs.
  • Actor type.
  • Actor status.
  • Assigned workspace path.
  • Assigned Gitea repo.
  • Assigned OpenCode server/workspace.
  • Last activity timestamp.
  • Billing entitlement status.

Initial endpoints:

  • POST /actors/provision
  • GET /actors/me
  • GET /actors/:actorId
  • POST /actors/:actorId/start
  • POST /actors/:actorId/stop
  • POST /actors/:actorId/message
  • GET /actors/:actorId/events

5.3 OpenCode Server Management API

The backend needs APIs to manage OpenCode resources:

  • Provision OpenCode workspace/server.
  • Start/stop OpenCode runtime.
  • Create coding sessions.
  • Send prompt/action to OpenCode.
  • Read execution status.
  • Fetch logs.
  • Restrict filesystem access.

Initial endpoints:

  • POST /opencode/provision
  • GET /opencode/workspaces/:workspaceId
  • POST /opencode/workspaces/:workspaceId/start
  • POST /opencode/workspaces/:workspaceId/stop
  • POST /opencode/workspaces/:workspaceId/sessions
  • POST /opencode/sessions/:sessionId/messages
  • GET /opencode/sessions/:sessionId/events

5.4 Gitea Management API

The backend needs APIs for:

  • Creating per-user repos.
  • Creating project repos.
  • Creating deploy keys or access tokens.
  • Committing memory/state files.
  • Reading repository status.
  • Managing branches.
  • Creating PRs when needed.

Initial endpoints:

  • POST /git/users/:userId/repo
  • GET /git/repos/:repoId
  • POST /git/repos/:repoId/commit
  • POST /git/repos/:repoId/branch
  • POST /git/repos/:repoId/pull-request

5.5 Payments

Payment controls whether the user's Grow Agent can be provisioned or run.

Requirements:

  • Checkout flow.
  • Webhook handling.
  • Subscription status.
  • Entitlement checks before actor startup.
  • Graceful suspension when payment fails.

Open decision:

  • Payment provider, likely Stripe.

6. Actor Requirements

6.1 Grow Agent Actor

State:

  • User profile summary.
  • Active goals.
  • Current quest/pathway.
  • Memory index.
  • Sub-agent registry.
  • Active tasks.
  • Git repo mapping.
  • OpenCode workspace mapping.
  • Recent conversation summary.

Actions:

  • Receive user message.
  • Update memory.
  • Start quest/pathway.
  • Spawn or call sub-agent.
  • Commit state to Git.
  • Request OpenCode session.
  • Emit progress event.

6.2 Sub-Agent Actor

State:

  • Parent Grow Agent ID.
  • Task type.
  • Current task status.
  • Workspace path.
  • Tool permissions.
  • Channel ID.
  • Logs/progress.

Actions:

  • Start task.
  • Pause/resume task.
  • Run bounded service action.
  • Run OpenCode action where allowed.
  • Commit output to Git.
  • Emit progress event.

7. Frontend Requirements

The frontend is next, but the backend should be shaped around this UI.

Primary screens:

  • Master Grow Agent chat.
  • Slack-like channel list.
  • Sub-agent channel/thread view.
  • Quest/pathway launcher.
  • Task progress timeline.
  • Files/repo activity view.
  • Billing/account state.

UI behavior:

  • User talks primarily to the Grow Agent.
  • Grow Agent messages can show spawned sub-agent activity.
  • Each sub-agent gets a visible channel or thread.
  • Quests/pathways appear as predefined flows that trigger agent prompts and actions.

8. Security and Isolation

Hard requirements:

  • Every user must have isolated directories.
  • Actors can only access assigned workspace roots.
  • OpenCode must run with strict workspace and command restrictions.
  • Gitea credentials must be scoped per user/repo where possible.
  • Backend must verify user ownership on every actor, repo, and OpenCode request.
  • Sub-agents should receive only the capabilities needed for their task.

9. MVP Scope

MVP Backend

  • User auth.
  • Actor registry.
  • One Grow Agent actor per user.
  • Basic sub-agent registration.
  • Per-user Gitea repo provisioning.
  • Basic Git-backed memory commits.
  • OpenCode workspace provisioning stub or integration.
  • Message endpoint from frontend to Grow Agent.
  • Event stream endpoint for progress.

MVP Frontend

  • Login.
  • Master chat interface.
  • Sub-agent progress sidebar.
  • Basic quest launcher.
  • Channel-style task logs.

MVP Actors

  • Grow Agent actor with memory and routing.
  • Coding sub-agent using OpenCode.
  • Repo sub-agent using Gitea.
  • Quest sub-agent using predefined prompts.
# Grow Agent Platform PRD ## 1. Overview GrowQR is a multi-agent development and personal growth platform where every user gets a dedicated master agent called a Grow Agent. The Grow Agent owns the user's long-running context, memory, workflows, files, repositories, execution state, and progress. The platform combines: - A Slack-like frontend for chat, progress, and sub-agent channels. - A dedicated Grow Agent per user. - Multiple specialized sub-agents per Grow Agent. - Git-backed memory and state using per-user repositories. - OpenCode-backed coding and execution environments. - Rivet Kit actors for durable state, orchestration, and actions. - Gitea for internal Git hosting and repository management. - Backend APIs for auth, actor registry, OpenCode server management, payments, and product flows. ## 2. Product Goals - Give every user a persistent AI workspace that can remember, plan, execute, and evolve over time. - Store all user agent state in Git so memory, files, decisions, and workflow history are inspectable and versioned. - Let a master Grow Agent orchestrate specialized sub-agents. - Give each sub-agent isolated execution scope, logs, state, and optionally a Slack-style channel. - Provide a frontend where users can talk to the Grow Agent, watch sub-agent progress, and trigger structured quests or pathways. - Support paid access where payment provisions and starts the user's Grow Agent environment. ## 3. Core Concepts ### 3.1 User A user is the primary account holder. Each user has: - One active Grow Agent. - One Lifelong Git repository for agent memory and workspace files. - Access to a dedicated OpenCode execution environment.(Agent) - Access to a Slack-like UI with channels for master and sub-agent activity. ### 3.2 Grow Agent The Grow Agent is the user's master agent and orchestration layer. Responsibilities: - Maintain user-level memory and context. - Decide which sub-agent should handle a task. - Trigger sub-agent workflows. - Track progress and state transitions. - Commit important state changes to the user's Git repo. - Coordinate OpenCode sessions for code execution. - Expose status to the frontend. The Grow Agent should be implemented as a durable actor, likely with Rivet Kit. ### 3.3 Sub-Agents Sub-agents are specialized workers owned by a Grow Agent. Examples: - Coding agent using OpenCode. - Repo setup agent using Gitea APIs. - Migration agent. - Product flow agent. - Payment/onboarding agent. - Quest/pathway agent. - Backend CRUD agent. - Frontend planning agent. Each sub-agent should have: - A unique actor identity. - A bounded workspace directory. - A bounded set of capabilities. - A dedicated state object. - A channel/thread in the frontend. - Optional backing microservice integration. ### 3.4 Git-Backed State Every user gets a Git repository that stores: - Agent memory files. - User goals and profile context. - Quest/pathway progress. - Plans, summaries, decisions, and task history. - Generated code/files. - Sub-agent outputs. - System state snapshots where appropriate. Gitea should be used as the internal Git server. Repository model: - One primary repo per user for Grow Agent memory and workspace state. - Optional child repos for generated products or user projects (for the workflows). - All writes from agents go through controlled Git actions. - Important state mutations should produce commits with structured messages. ### 3.5 OpenCode Execution OpenCode is used as the code execution and coding-agent interface. Expected model: - Each user gets access to an OpenCode server or OpenCode workspace. - OpenCode runs with strict directory boundaries. - The Grow Agent can create sessions, send prompts, inspect results, and receive progress. - Coding sub-agents use OpenCode to edit code, run commands, and report status. - one OpenCode container per actor ## 4. System Architecture ### 4.1 High-Level Components - Frontend app: Slack-like UI, chat interface, quests/pathways, progress views. - Backend API: auth, billing, user management, actor registry, OpenCode management, Gitea management. - Rivet Kit actor runtime: durable Grow Agent and sub-agent actors. - Gitea: internal Git hosting for per-user repos. - OpenCode server: coding and command execution environment. - Database: relational app data such as users, auth, billing, actor registry metadata, and repo mappings. - Queue/event layer: optional event delivery between backend, actors, OpenCode, and frontend. ### 4.2 Request Flow 1. User signs up or logs in. 2. Payment or plan check confirms entitlement. 3. Backend provisions the user's Grow Agent. 4. Backend creates or links the user's Gitea repo. 5. Backend creates or links the user's OpenCode workspace/server. 6. User sends a message in the frontend. 7. Message is routed to the user's Grow Agent actor. 8. Grow Agent updates state, decides whether to call sub-agents, and commits durable context to Git when needed. 9. Sub-agents run tasks using bounded tools, microservices, Git actions, or OpenCode. 10. Progress events stream back to the frontend. ## 5. Backend Requirements ### 5.1 Auth The backend must support: - User registration and login. - using clerk - Per-user authorization checks for all actor, repo, and OpenCode resources. - Service-to-service auth for actors calling backend APIs. ### 5.2 Actor Registry API The backend needs an actor registry that tracks: - User ID. - Grow Agent actor ID. - Sub-agent actor IDs. - Actor type. - Actor status. - Assigned workspace path. - Assigned Gitea repo. - Assigned OpenCode server/workspace. - Last activity timestamp. - Billing entitlement status. Initial endpoints: - `POST /actors/provision` - `GET /actors/me` - `GET /actors/:actorId` - `POST /actors/:actorId/start` - `POST /actors/:actorId/stop` - `POST /actors/:actorId/message` - `GET /actors/:actorId/events` ### 5.3 OpenCode Server Management API The backend needs APIs to manage OpenCode resources: - Provision OpenCode workspace/server. - Start/stop OpenCode runtime. - Create coding sessions. - Send prompt/action to OpenCode. - Read execution status. - Fetch logs. - Restrict filesystem access. Initial endpoints: - `POST /opencode/provision` - `GET /opencode/workspaces/:workspaceId` - `POST /opencode/workspaces/:workspaceId/start` - `POST /opencode/workspaces/:workspaceId/stop` - `POST /opencode/workspaces/:workspaceId/sessions` - `POST /opencode/sessions/:sessionId/messages` - `GET /opencode/sessions/:sessionId/events` ### 5.4 Gitea Management API The backend needs APIs for: - Creating per-user repos. - Creating project repos. - Creating deploy keys or access tokens. - Committing memory/state files. - Reading repository status. - Managing branches. - Creating PRs when needed. Initial endpoints: - `POST /git/users/:userId/repo` - `GET /git/repos/:repoId` - `POST /git/repos/:repoId/commit` - `POST /git/repos/:repoId/branch` - `POST /git/repos/:repoId/pull-request` ### 5.5 Payments Payment controls whether the user's Grow Agent can be provisioned or run. Requirements: - Checkout flow. - Webhook handling. - Subscription status. - Entitlement checks before actor startup. - Graceful suspension when payment fails. Open decision: - Payment provider, likely Stripe. ## 6. Actor Requirements ### 6.1 Grow Agent Actor State: - User profile summary. - Active goals. - Current quest/pathway. - Memory index. - Sub-agent registry. - Active tasks. - Git repo mapping. - OpenCode workspace mapping. - Recent conversation summary. Actions: - Receive user message. - Update memory. - Start quest/pathway. - Spawn or call sub-agent. - Commit state to Git. - Request OpenCode session. - Emit progress event. ### 6.2 Sub-Agent Actor State: - Parent Grow Agent ID. - Task type. - Current task status. - Workspace path. - Tool permissions. - Channel ID. - Logs/progress. Actions: - Start task. - Pause/resume task. - Run bounded service action. - Run OpenCode action where allowed. - Commit output to Git. - Emit progress event. ## 7. Frontend Requirements The frontend is next, but the backend should be shaped around this UI. Primary screens: - Master Grow Agent chat. - Slack-like channel list. - Sub-agent channel/thread view. - Quest/pathway launcher. - Task progress timeline. - Files/repo activity view. - Billing/account state. UI behavior: - User talks primarily to the Grow Agent. - Grow Agent messages can show spawned sub-agent activity. - Each sub-agent gets a visible channel or thread. - Quests/pathways appear as predefined flows that trigger agent prompts and actions. ## 8. Security and Isolation Hard requirements: - Every user must have isolated directories. - Actors can only access assigned workspace roots. - OpenCode must run with strict workspace and command restrictions. - Gitea credentials must be scoped per user/repo where possible. - Backend must verify user ownership on every actor, repo, and OpenCode request. - Sub-agents should receive only the capabilities needed for their task. ## 9. MVP Scope ### MVP Backend - User auth. - Actor registry. - One Grow Agent actor per user. - Basic sub-agent registration. - Per-user Gitea repo provisioning. - Basic Git-backed memory commits. - OpenCode workspace provisioning stub or integration. - Message endpoint from frontend to Grow Agent. - Event stream endpoint for progress. ### MVP Frontend - Login. - Master chat interface. - Sub-agent progress sidebar. - Basic quest launcher. - Channel-style task logs. ### MVP Actors - Grow Agent actor with memory and routing. - Coding sub-agent using OpenCode. - Repo sub-agent using Gitea. - Quest sub-agent using predefined prompts.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
dv OG puter Sai-karthik
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: growqr-app/growqr-backend#1
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?