🎯

00-Product-Overview

📌

Mirror of docs/PROJECT_CONTEXT.md — the canonical product overview consumed by Cursor, Claude Code, and onboarding humans.

1. Product Statement

AI Coding Agent Workspace is a server-hosted application for running AI coding agents inside real software projects. Users give an agent a real coding task ("add a /api/invoices endpoint with PDF export"), and the system manages the full workflow: workspace, code inspection, RAG context, file edits, terminal commands, Git, snapshots, revisions, documentation updates, live console logs, and safe recovery.

It is not a chatbot. It is an execution platform with full auditability.

2. Primary Personas

PersonaGoalPain solved
Solo founder / lead engineerShip features faster without giving up control.Cursor/Claude in a real repo, observable from iPhone, with rollback.
Small team tech leadDelegate well-scoped tasks to an agent and review diffs.Branch-per-run + reviewable diffs + audit log.
Architect / consultantOnboard fast to unknown codebases.Auto-generated PROJECT_MAP + RAG-grounded answers.

3. Outcomes the system must enable

The agent must be able to:

  • inspect the codebase
  • understand routes, controllers, models, migrations, services, jobs, events, policies, config
  • understand database structure and relationships
  • understand how every route ↔ controller ↔ model ↔ table is connected
  • use RAG before making decisions
  • modify files safely
  • run allowed commands
  • pause for user input
  • resume from the correct point
  • track every event, file change, snapshot, command, doc update, and Git op
  • show live console logs
  • update documentation automatically
  • integrate with OpenAI API, Claude API, Claude Code, and Git
  • expose an iPhone-first mobile API

4. Top-level user stories

  • US-1 As a user, I create a project from a Git URL and the system clones, indexes, and generates a PROJECT_MAP automatically.
  • US-2 As a user, I write a task prompt, pick an agent and model, toggle RAG and safe mode, and start a run.
  • US-3 As a user, I watch the live console on my iPhone and see every step, every command, every diff.
  • US-4 As a user, I receive a waiting_for_user event when the agent needs a decision, answer it from the iPhone, and the run resumes.
  • US-5 As a user, I review the final diff, approve, optionally commit on the run branch, and optionally push (never automatic).
  • US-6 As a user, I can restore any snapshot at any time.
  • US-7 As a user, I can search documentation and the project map from the iPhone.

5. Success metrics (v1)

  • TTFE (time-to-first-event) after starting a run < 3 s.
  • Run resumability: 100% of paused runs resume to the correct step.
  • Auditability: 100% of file changes have before/after hash, diff, and snapshot reference.
  • Recoverability: any run can be rolled back in ≤ 30 s.
  • iPhone latency: SSE event delivery p95 < 1 s.

6. Out of scope for v1

  • Android client.
  • Multi-tenant org/team model (single owner + API tokens only).
  • Web IDE / in-browser file editing.
  • Automatic push to remote (always manual).
  • Running unsigned shell commands.

7. Cross-references

  • Stack & platform: see 01 — Platform Strategy & Stack.
  • Data model: see 02 — Backend Modules & Data Model.
  • Agent design: see 05 — Agent Providers & Specialized Agents.
  • iPhone UX: see 13 — iPhone SwiftUI App Spec.