AGENTS.md git:20260410.687935eA

Immutable. This exact content never changes and is served at /api/v1/blob/812578daff03ab92.

# CodeFRAME Development Guidelines (v2)

Last updated: 2026-04-09

**Status: CLI ✅ | Server ✅ | ReAct agent ✅ | Web UI ✅ | Agent adapters ✅ | Multi-provider LLM ✅ | Phase 3.5B ✅ | Next: Phase 3.5C**

CodeFRAME is a **project delivery system**: Think → Build → Prove → Ship. It owns the edges of the AI coding pipeline — everything before code gets written (PRD, specification, task decomposition) and everything after (verification gates, quality memory, deployment). The actual coding is delegated to frontier agents.

**CodeFRAME does not compete with coding agents. It orchestrates them.**

If you are an agent working in this repo: **do not improvise architecture**. Follow the documents listed below.

---

## 🚦 Primary Contract (MUST FOLLOW)

1. **Golden Path**: `docs/GOLDEN_PATH.md` — the only workflow we build until it works end-to-end
2. **Command Tree + Module Mapping**: `docs/CLI_WIREFRAME.md` — CLI commands → core modules
3. **Product Roadmap**: `docs/PRODUCT_ROADMAP.md` — current phase plan (Phase 3.5/4/5)
4. **Vision**: `docs/VISION.md` — north star for all decisions
5. **Agent System Reference**: `docs/AGENT_SYSTEM_REFERENCE.md` — agent components, execution flows

**Rule 0:** If a change does not directly support the Think → Build → Prove → Ship pipeline, do not implement it.

---

## Current Architecture (v2)

- **Core-first**: Domain logic lives in `codeframe/core/` — headless, no FastAPI imports
- **CLI-first**: Golden Path works **without any running FastAPI server**
- **Server optional**: FastAPI (`codeframe/ui/`) is a thin adapter over core, started explicitly via `codeframe serve`
- **Web UI optional**: Next.js frontend (`web-ui/`) connects to the server via REST and WebSocket
- **Adapters**: LLM providers in `codeframe/adapters/llm/`
- **Default engine**: ReAct (observe → think → act loop) — legacy plan engine available via `--engine plan`

The architecture is layered — CLI and server call the same core modules. The web UI calls the server. No layer bypasses its boundary.

---

## Repository Structure

```
codeframe/
├── core/                    # Headless domain + orchestration (NO FastAPI imports)
│   ├── react_agent.py      # ReAct agent (default engine)
│   ├── tools.py            # Tool definitions (7 tools)
│   ├── editor.py           # Search-replace file editor with fuzzy matching
│   ├── agent.py            # Legacy plan engine (--engine plan)
│   ├── planner.py, executor.py   # Plan engine internals
│   ├── runtime.py          # Run lifecycle + engine selection
│   ├── conductor.py        # Batch orchestration + worker pool
│   ├── tasks.py, blockers.py, prd.py, workspace.py
│   ├── gates.py, fix_tracker.py, quick_fixes.py  # Verification + self-correction
│   ├── stall_detector.py, stall_monitor.py
│   ├── dependency_graph.py, dependency_analyzer.py
│   ├── context.py, state_machine.py, events.py, streaming.py
│   ├── environment.py, installer.py, diagnostics.py
│   ├── credentials.py, agents_config.py
│   └── sandbox/            # Worktree + E2B isolation abstractions
├── adapters/
│   ├── llm/                # LLM provider adapters (anthropic, openai-compatible, mock)
│   └── e2b/                # Cloud sandbox (optional)
├── cli/app.py              # Typer CLI entry + subcommands
├── ui/                     # FastAPI server (thin adapter over core)
│   ├── server.py, models.py, dependencies.py
│   └── routers/            # 16 v2 router modules
├── auth/                   # API key service + auth dependencies
├── lib/                    # rate_limiter.py, audit_logger.py
└── server/                 # Legacy v1 (reference only — do not import)

web-ui/                     # Next.js 16 frontend (actively developed)
├── src/
│   ├── app/                # App Router pages (/, /prd, /tasks, /execution, /blockers,
│   │                       #   /proof, /proof/[req_id], /review, /sessions, /sessions/[id])
│   ├── components/
│   │   ├── ui/             # Shadcn/UI base components
│   │   ├── layout/         # AppLayout, AppSidebar, PipelineProgressBar
│   │   ├── workspace/      # Workspace view components
│   │   ├── prd/            # PRD discovery, upload, version history
│   │   ├── tasks/          # Kanban board, task detail, batch actions
│   │   ├── execution/      # EventStream, SSE monitor
│   │   ├── blockers/       # Blocker resolution
│   │   ├── review/         # Diff viewer, commit panel, file tree
│   │   ├── proof/          # Gate run panel, evidence panel, run history
│   │   └── sessions/       # Agent chat, XTerm.js terminal, SplitPane
│   ├── hooks/              # useEventSource, useTaskStream, useProofRun, useAgentChat, useTerminalSocket
│   ├── lib/                # api.ts, diffParser.ts, utils.ts, workspace-storage.ts
│   └── types/              # TypeScript type definitions
└── src/__tests__/          # Jest unit tests

tests/
├── core/                   # Core module tests (auto-marked v2)
├── adapters/               # LLM + E2B adapter tests
├── agents/                 # Worker agent tests
├── integration/            # Cross-module integration tests
├── lifecycle/              # End-to-end lifecycle tests (uses MockProvider)
└── ui/                     # FastAPI router tests
```

---

## Architecture Rules (non-negotiable)

### 1) Core must be headless
`codeframe/core/**` must NOT import FastAPI, WebSocket frameworks, HTTP request/response objects, or UI modules.

### 2) CLI must not require a server
Golden Path commands must work from the CLI with **no server running**. FastAPI is optional.

### 3) Agent state transitions flow through runtime
- Agent manages its own `AgentState` (IDLE, PLANNING, EXECUTING, BLOCKED, COMPLETED, FAILED)
- Runtime handles all `TaskStatus` transitions (BACKLOG, READY, IN_PROGRESS, DONE, BLOCKED)
- Agent does NOT call `tasks.update_status()` — runtime does this based on agent state

### 4) Legacy can be read, not depended on
Do NOT import `server/` (v1) modules into core. `server/` is reference only.

### 5) Keep commits runnable
`codeframe --help` must work at all times. No breaking renames or moves without keeping the path runnable.

---

## Agent System

### Engine Selection

| Engine | Flag | Pattern | Best For |
|--------|------|---------|----------|
| **ReAct** (default) | `--engine react` | Observe → Think → Act loop | Most tasks, adaptive execution |
| **Plan** (legacy) | `--engine plan` | Plan all steps → Execute sequentially | Well-defined, predictable tasks |
| **External adapters** | `--engine claude-code` etc. | Delegate to external agent | When a frontier agent is preferred |

### ReAct Agent Tools (7)
`read_file`, `edit_file`, `create_file`, `run_command`, `run_tests`, `search_codebase`, `list_files`

### Stall Detection
If the agent makes no tool calls for a configurable duration, the stall monitor kills execution and creates a blocker.

| Setting | Default |
|---------|---------|
| `--stall-timeout` CLI flag | 300s |
| `agent_budget.stall_timeout_s` in `.codeframe/config.yaml` | 300s |

### Model Selection
- **PLANNING** → `claude-sonnet-4-20250514` (complex reasoning)
- **EXECUTION** → `claude-sonnet-4-20250514` (balanced)
- **GENERATION** → `claude-haiku-4-20250514` (fast)

---

## Commands

### Quality checks
```bash
uv run pytest                    # All Python tests
uv run pytest -m v2              # v2 tests only
uv run pytest tests/core/        # Core module tests
uv run ruff check .              # Linting

cd web-ui && npm test            # Frontend Jest tests
cd web-ui && npm run build       # Production build verification
```

### Golden Path CLI
```bash
cf init <repo> [--detect]        # Initialize workspace
cf status

cf prd add <file.md>
cf prd show

cf tasks generate
cf tasks list [--status READY]
cf tasks show <id>

cf work start <task-id> [--execute] [--engine react|plan] [--verbose]
cf work start <task-id> --execute --llm-provider openai --llm-model gpt-4o
cf work batch run [--all-ready] [--strategy serial|parallel|auto] [--retry 3]
cf work follow <task-id>
cf work stop <task-id>
cf work resume <task-id>

cf blocker list
cf blocker answer <id> "answer"

cf proof run
cf proof capture
cf proof list / status / show <id> / waive <id>

cf pr create / status / checks / merge
```

---

## Web UI

The web UI is built on top of the v2 CLI and API — it does not contain independent business logic. All data flows through the FastAPI server, which wraps core.

**Stack**: Next.js 16, TypeScript, Shadcn/UI (Nova preset, gray palette), Hugeicons (`@hugeicons/react`), Tailwind CSS, XTerm.js, WebSocket + SSE

**Never use lucide-react** — all icons via `@hugeicons/react`.

### Shipped pages
| Route | Feature |
|-------|---------|
| `/` | Workspace dashboard, onboarding, pipeline status |
| `/prd` | PRD editor with Socratic discovery, version history, diff/restore |
| `/tasks` | Kanban board, batch execution, bulk stop/reset, task detail modal |
| `/execution/[taskId]` | Live SSE event stream, execution monitor |
| `/blockers` | Blocker resolution with lifecycle guidance |
| `/review` | Diff viewer, file tree, commit panel, PR creation |
| `/proof` | PROOF9 gate list, evidence display, run history, waiver with audit trail |
| `/proof/[req_id]` | Requirement detail, evidence history |
| `/sessions` | Agent sessions list |
| `/sessions/[id]` | Agent chat panel (tool calls, thinking blocks) + XTerm.js terminal |

### Key patterns
- All API endpoints require `workspace_path` query parameter
- Types in `web-ui/src/types/index.ts`, API client in `web-ui/src/lib/api.ts`
- SSE hooks: `useEventSource.ts` (generic) + `useTaskStream.ts` (typed execution events)
- Test mocks for `@hugeicons/react` in `web-ui/__mocks__/@hugeicons/react.js`
- `npm test` and `npm run build` must pass before any web-facing PR

---

## What NOT to do

- Don't add HTTP endpoints to support CLI commands — CLI must work without a server
- Don't require `codeframe serve` for CLI workflows
- Don't implement UI concepts (tabs, panels, progress bars) inside `codeframe/core/`
- Don't update task status from `agent.py` — let `runtime.py` handle transitions
- Don't import from `server/` (v1) into core or ui
- Don't leave a CI gate disabled when its feature area becomes active
- Don't "clean up the repo" as a goal — only refactor to enable the pipeline
- Don't skip web UI testing (`npm test`, `npm run build`) when changing web-facing code

---

## Practical Working Mode

1. Read `docs/GOLDEN_PATH.md` — confirm the change is required
2. Find the command in `docs/CLI_WIREFRAME.md`
3. Implement core functionality in `codeframe/core/`
4. Call it from Typer command in `codeframe/cli/`
5. Emit events + persist state
6. Keep it runnable. Commit.

When unsure: simpler state, fewer dependencies, smaller surface area, core-first, CLI-first.