# Forge Agent Polished browser-based AI coding-agent workspace for chat-driven mock builds, file editing, task tracking, automations, previews/checks, and a secure backend AI proxy stub. ## Masterplan - Deliver a Replit-style builder loop: users describe a change, AI returns complete file contents, Forge Agent applies them to a mock workspace, and users inspect/refine/check the result. - Serve builders, founders, and developers who want a Claude-like coding assistant UI in-browser before connecting a real filesystem/runtime agent. - Keep the current product as a high-fidelity frontend prototype: workspace files, chat history, tasks, active file, mode, and theme persist locally. - Preserve “build, don’t only explain”: successful AI responses must parse as JSON file changes and be applied through `useAgentStore.applyBuildChanges()`. - Use the hosted `/api/ai/completion` text-generation capability from the browser today; `backend/handlers/agent.py` is a production-safe proxy stub and is not wired to the frontend yet. ## Tech Stack & Architecture - Static no-build browser app loaded by `index.html`. - Runtime/CDN dependencies: - Tailwind CDN via `https://cdn.tailwindcss.com` - React `19.2.0` - ReactDOM `19.2.0` - React Router DOM `7.9.4` - Zustand `5.0.8` - htm `3.1.1` - lucide-react `0.468.0` - No JSX compilation. Components use `src/jsx.js`, which binds `htm` to `React.createElement`. - Use tagged templates: ``html`<${Component} prop=${value} />` ``. - Do not write raw JSX unless adding a build pipeline. - Bootstrap: - `index.html` loads Tailwind, `styles/main.css`, then `src/main.js`. - `src/main.js` renders `` into `#root`. - `src/mainProviders.js` owns theme context, persists `forge-theme`, and toggles `.dark` on ``. - Routing: - `src/App.js` uses `HashRouter`; routes are static-hosting safe. - `src/components/Layout.js` wraps all pages with `Header` and a centered `max-w-7xl` main area. - Routes: - `#/` → `src/pages/Home.js` - `#/workspace` → `src/pages/Workspace.js` - `#/automations` → `src/pages/Automations.js` - `#/settings` → `src/pages/Settings.js` - wildcard → `src/pages/NotFound.js` - State: - `src/store/useAgentStore.js` is the single workspace store. - Zustand persist key: `forge-agent-workspace`. - Theme is intentionally separate from workspace state, with key `forge-theme`. - Workspace state includes `files`, `tasks`, `messages`, `consoleLogs`, `activeFileId`, `agentMode`, and `isRunning`. - AI flow: - `src/components/AgentChat.js` posts directly to `/api/ai/completion`. - Request body: ```js { prompt: aiPrompt, appId: window.GENMB_APP_ID, maxTokens: 1600 } ``` - Prompt includes current mock file contents capped to 9000 chars, last 8 chat messages, and `agentMode`. - AI is instructed to return only valid JSON: ```json { "summary": "short build summary", "files": [{ "name": "src/App.js", "content": "complete file content" }], "notes": ["verification note"] } ``` - `extractBuild()` strips markdown fences, extracts the first JSON object, validates `files`, then `applyBuildChanges()` creates/replaces mock files. - On success: assistant summary is added, changed file names are listed, `task-3` is marked done, and a temporary success alert appears. - On failure: an assistant error message is added and the chat error banner is shown. - Backend stub: - `backend/handlers/agent.py` exposes `POST /` for a future FastAPI custom route. - Request model: `{ prompt: string, mode: string = "builder" }` - Response model: `{ reply: string, provider: string, connected: boolean }` - If `AI_API_KEY` is missing, returns a local simulation. - If configured, attempts a placeholder provider call to `https://api.your-ai-provider-here.invalid/v1/messages`. - This route is not currently used by `AgentChat.js`. If wiring it, update frontend request/response parsing and Settings copy together. ## File Structure ```text CLAUDE.md # Project/agent documentation; keep synced with actual architecture and AI flow. backend/handlers/agent.py # FastAPI proxy stub for future server-side provider integration. index.html # Static entry; loads Tailwind CDN, styles/main.css, and src/main.js. styles/main.css # Theme tokens, dark tokens, glass/card utilities, code font, animations, focus ring. src/jsx.js # htm binding; required by all component files instead of JSX compilation. src/main.js # ReactDOM bootstrap into #root with Providers and App. src/mainProviders.js # ThemeProvider/useTheme; persists forge-theme and toggles .dark. src/App.js # HashRouter route table and shared Layout nesting. src/store/useAgentStore.js # Persisted Zustand workspace store, mock files/tasks/messages, build checks. src/components/Layout.js # Header + centered page shell. src/components/Header.js # Brand, route nav, theme toggle, Start building CTA. src/components/AgentChat.js # AI builder chat, /api/ai/completion call, JSON extraction, file application. src/components/CodeEditor.js # Active mock file textarea, reset button, Build project static checks/console. src/components/FileExplorer.js # File list, active file selection, task progress sidebar. src/pages/Home.js # Landing page, feature cards, CTA into workspace. src/pages/Workspace.js # Three-panel builder layout: files, editor, chat. src/pages/Automations.js # Static automation library cards. src/pages/Settings.js # Agent mode selector and endpoint/secrets guidance. src/pages/NotFound.js # 404 fallback. ``` ## Key Features - **AI builder chat** - Implemented in `src/components/AgentChat.js`. - User submits natural-language build requests. - While `isRunning` is true, duplicate submissions are blocked. - Uses current `files`, recent `messages`, and `agentMode` to produce a strict JSON build prompt. - Accepts only JSON containing a `files` array; prose-only AI output is treated as failure. - Supports returned file keys `name` or `path`. - **Mock workspace files** - Source of truth: `files` array in `src/store/useAgentStore.js`. - File model: ```js { id: 'file-app', name: 'src/App.js', language: 'javascript', status: 'edited' | 'created' | 'planned', content: '...' } ``` - Initial mock files: - `src/App.js` - `styles/main.css` - `backend/handlers/agent.py` - `applyBuildChanges(changes)` updates matching `name` files or creates new entries. - New file language is inferred by extension: `.css`, `.py`, `.html`, otherwise `javascript`. - After applying changes, the active file becomes the last file in the workspace list, not necessarily the last changed file. - **Code editor** - Implemented in `src/components/CodeEditor.js`. - Plain `

`, not Monaco/CodeMirror.
  - Editing a file calls `updateFileContent()` and marks status `edited`.
  - `Reset` calls `resetWorkspace()` and clears persisted workspace back to initial state.
- **Build project checks**
  - Implemented in `useAgentStore.runBuild()`, triggered by `CodeEditor`.
  - Static mock validation only; no real bundling or execution.
  - Fails if:
    - `src/App.js` is missing.
    - any file content is empty.
    - a `.js` file contains `class=` because htm requires `className=`.
    - a `.js` file contains literal `</script>`.
  - On success, marks `task-4` done.
- **Tasks**
  - Stored in `tasks`.
  - Initial tasks:
    - Understand product goal: done
    - Generate app structure: done
    - Apply AI build changes: pending
    - Run preview checks: pending
  - Successful AI build marks `task-3` done.
  - Successful build checks mark `task-4` done.
- **Agent modes**
  - Controlled in `src/pages/Settings.js` with values:
    - `builder`
    - `reviewer`
    - `architect`
  - Mode is included in AI prompt and displayed in chat.
- **Automations library**
  - Static cards in `src/pages/Automations.js`.
  - Represents future routines: design polish, runtime repair, data model planning, refactoring, performance review, provider connector.
- **External integrations**
  - Active frontend AI integration: `POST /api/ai/completion`, expecting `json.data.text`.
  - Future backend integration: `backend/handlers/agent.py`, server-side `AI_API_KEY`, placeholder provider endpoint.

## Design Guidelines
- Visual style: polished AI workspace with glassmorphism, rounded panels, gradient background, and Replit-like multi-panel layout.
- Theme tokens live in `styles/main.css` as HSL CSS variables:
  - Primary purple: `--primary`
  - Secondary cyan: `--secondary`
  - Accent amber: `--accent`
  - Success green: `--success`
  - Destructive red: `--destructive`
- Dark mode is token-based via `.dark` on `<html>`.
- Typography:
  - App font: `Inter, ui-sans-serif, system-ui, ...`
  - Code surfaces: `"SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace` through `.code-pane`.
- Common UI patterns:
  - Use `.glass` for cards/panels.
  - Use `.focus-ring` on interactive elements.
  - Use `rounded-[var(--radius-lg)]` for major surfaces.
  - Use Tailwind utility classes with token references like `hsl(var(--primary))`.
- Responsive behavior:
  - `Workspace.js` is single-column on small screens, two columns at `lg`, and three columns at `xl`.
  - Header stacks on small screens and becomes horizontal from `md`.
  - Home feature cards progress from one column to two to four.

## App Flow
- **Landing to workspace**
  1. User opens `#/`.
  2. `Home.js` explains builder loop.
  3. “Start building” links to `#/workspace`.
- **Build with AI**
  1. User enters a prompt in `AgentChat`.
  2. Chat appends a user message and sets `isRunning`.
  3. App sends strict JSON build prompt to `/api/ai/completion`.
  4. Response text is parsed by `extractBuild()`.
  5. `applyBuildChanges()` updates/creates mock files.
  6. Chat displays summary, changed file names, and notes.
  7. User inspects files in `FileExplorer` and `CodeEditor`.
- **Manual edit and check**
  1. User selects a file in `FileExplorer`.
  2. User edits content in `CodeEditor`.
  3. User clicks “Build project”.
  4. Static checks update `consoleLogs`; success marks preview task complete.
- **Settings**
  1. User opens `#/settings`.
  2. User changes operating mode.
  3. Future AI prompts include that mode.
- **Edge cases**
  - Empty prompt or running request: submit is ignored.
  - AI HTTP 429: shows rate-limit copy.
  - Empty AI text: treated as failed build.
  - Non-JSON or JSON without `files`: treated as failed build.
  - Empty returned file content is ignored by `applyBuildChanges()`.
  - Persisted workspace may hide new defaults during development; use Reset or clear `forge-agent-workspace`.

## Conventions
- Use ES modules everywhere; imports are direct file paths or esm.sh CDN URLs.
- Always import `html` from `src/jsx.js` and write htm templates, not JSX.
- htm gotchas:
  - Use `className`, not `class`, in generated React elements.
  - Interpolate components as `<${Component} />`.
  - Close dynamic components as `</${Component}>` when needed.
  - Event handlers are passed as expressions: `onClick=${handler}`.
- Store conventions:
  - Add workspace behavior in `src/store/useAgentStore.js`.
  - Keep theme behavior in `src/mainProviders.js`.
  - Persisted workspace changes should remain serializable.
- Styling conventions:
  - Prefer Tailwind utilities plus CSS variables from `styles/main.css`.
  - Add reusable global effects/classes only when used by multiple components or animations.
- Adding a page:
  1. Create `src/pages/NewPage.js`.
  2. Import it in `src/App.js` and add a `<Route>`.
  3. Add a nav link in `src/components/Header.js` if it is primary navigation.
- Adding a workspace feature:
  1. Extend `useAgentStore.js` with state/actions.
  2. Consume state through selectors in components.
  3. If AI should control it, update the prompt contract in `AgentChat.js`.
  4. If the output contract changes, update `extractBuild()`, error handling, and Settings/help copy.
- Backend integration convention:
  - Do not expose provider keys in browser code.
  - Customize `backend/handlers/agent.py` for real provider calls.
  - If replacing `/api/ai/completion`, update `AgentChat.js` to match the new response shape and keep strict JSON file-change parsing.

## Platform (GenMB)

This app is built and hosted on GenMB.

**Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists.

**Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime.

**Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config.

**Built-in services (relative API paths only, never hardcode domains):**
- `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK)
- `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth
- `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth`

**File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file).

**Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.
</article></body></html>