[zwanski-start]

Closes #134

What changed

Adds an Import Existing Codebase onboarding flow for folders that already contain code. Claude:

1. Reads the codebase (Read/Glob/Grep only, no Bash) and presents its understanding: what the app is, its stack, what it already does and what looks unfinished. It then waits for the user to confirm or correct this.
2. Writes .autoforge/prompts/app_spec.txt describing the app as it exists today.
3. Records the existing functionality as features already marked passing, so the coding agent doesn't rebuild them.
4. Plans new features and improvements with the user and adds them as pending features.

Because features now exist, pressing Play starts the normal coding agent (not the initializer) on the existing code.

Entry points

• New-project wizard: a third setup method, "Import Existing Codebase".
• "Project Setup Required" screen: an "Import Existing Code" card.

Backend

• New skill .claude/commands/onboard-project.md (also usable as /onboard-project in Claude Code).
• ExpandChatSession gains mode: "expand" | "onboard". The expand WebSocket accepts ?mode=onboard and skips the "spec must exist" check in that mode. The unmodified scaffold app_spec.txt template is removed so Claude can write the spec fresh.
• In onboard mode Write/Edit are allowed, but a PreToolUse hook blocks writes to any path except app_spec.txt, so user source code can't be modified. Bash stays denied.
• feature_create_bulk accepts an optional per-feature "passes": true. The default is unchanged (false), and non-boolean values are rejected.
• The chat now counts feature_create_bulk results and emits features_created. Previously this counter was never updated, in the existing Expand chat as well.

How I verified it

• ruff check . passes, and so do python test_security.py, the new test_onboard_project.py (write hook incl. traversal, result parsing, passes flag) and the client, dependency-resolver and WebSocket tests.
• ui: npm run lint shows only warnings that were already there, and npm run build succeeds.
• Manual end-to-end run on port 5345 with an isolated registry, against a small stub Express project. Both entry points render and open the chat. Through the UI, Claude explored the code, asked for confirmation, wrote app_spec.txt and created pending features. The project's source file was left unchanged.

Assumptions / notes

• Existing features are recorded as passing based on Claude's code reading. The regression testing agents will re-verify them later.
• The new-project wizard registers the folder with specMethod: 'manual' (which scaffolds prompts) before onboarding. spec_method isn't used server-side.
• Known limitation (also affects the existing Expand chat): if the browser WebSocket reconnects in the middle of a turn, the rest of that reply isn't delivered and the UI keeps showing "thinking". Onboarding turns are longer (a minute or more of exploration), so this is more likely to show up there. I saw it twice in testing; the final run completed normally. A follow-up should make sessions survive reconnects (e.g. decouple the SDK stream from the WebSocket handler task).
• This PR comes from a fork because the agent account has read-only access to the upstream repo.

QA round 1 follow-up

• Reachable entry point for registered projects: registering a folder scaffolds a template app_spec.txt, which check_spec_exists counts as a spec. So the "Project Setup Required" screen, and its Import card, never showed for a project added on top of existing code. The empty Kanban board's Pending column now shows an Import Existing Code button whenever the project has no features. Once onboarding removes the template, the setup screen also shows the Import card. I didn't change check_spec_exists on purpose: it is shared with the start.py CLI.
• mcp>=1.0.0,<2.0.0 pinned in requirements.txt / requirements-prod.txt. A fresh install now pulls mcp 2.x, which renamed FastMCP, and that broke mcp_server/feature_mcp.py and test_onboard_project.py at import time.
• Re-verified: ruff check ., python test_security.py, pytest test_onboard_project.py test_client.py test_dependency_resolver.py test_rate_limit_utils.py (63 passed), npm run lint (0 errors), npm run build. Browser check on port 5820 with an isolated HOME: the Kanban button opens the onboarding chat (?mode=onboard), the scaffold template is deleted, the stub source is untouched, and the setup screen shows three cards. The Claude turn itself wasn't re-run, because the isolated HOME has no login.

🤖 Generated with Claude Code

[zwanski-start]

🔍 QA report: ✅ Passed

Tester: Ada (cubefarm agent, in a fresh session) · Round: 2 · Author: Guido

The onboarding flow works and meets issue #134: an existing codebase can be imported from the new-project wizard, the Project Setup screen, or the empty Kanban board, and it opens an onboard-mode chat that analyses the code, writes app_spec.txt, records existing features as passing and plans new ones. A PreToolUse hook limits writes to app_spec.txt, Bash stays denied, and feature_create_bulk's new 'passes' flag defaults to false and rejects non-booleans. ruff, the security tests, the 8 new tests, the UI build and lint all pass; the mypy and pytest failures are the same as on master, and with no Claude CLI it shows a clear error.

	Check	Details
✅	Issue #134 requirements: analyse code, record existing features, plan new ones	Reviewed .claude/commands/onboard-project.md and ExpandChatSession onboard mode: explore with Read/Glob/Grep, confirm with the user, write the spec, feature_create_bulk with passes:true for existing features, then pending features for new work.
✅	Writes limited to app_spec.txt; Bash denied	The hook allows only the resolved spec path and blocks source files, traversal paths and calls with no path; it uses the same {decision: block} format as security.py. Bash and MultiEdit/NotebookEdit stay in disallowed_tools. Unit tests cover these cases.
✅	feature_create_bulk passes flag	Defaults to false; passes=true is stored; passes='yes' returns an error (tested in test_onboard_project.py).
✅	WebSocket mode handling	?mode=bogus -> error and close code 4000; expand with no spec -> 4004 as before; onboard with no spec gets through; unknown project -> 4004.
✅	Works with no Claude CLI	With the Claude CLI off PATH, the onboarding chat shows 'Claude CLI not found' with no crash. No paid API calls were made.
✅	Only the scaffold template is removed; real spec kept	The template app_spec.txt was deleted on onboard start; a hand-written app_spec.txt was kept. Source files in the stub projects kept the same checksum.
✅	Kanban empty-board Import Existing Code entry point	The button appears in the Pending column when there are no features and opens the 'Import Existing Project: stubapp' chat (WebSocket opened with ?mode=onboard).
✅	Project Setup Required screen shows 3 cards	After the template was removed the setup screen shows Create with Claude / Import Existing Code / Edit Templates; Analyze Codebase opens the onboarding chat.
✅	New-project wizard Import Existing Codebase method	Name -> folder -> Blank -> Import Existing Codebase registers the folder and opens the onboarding chat; main.py unchanged.
✅	Phone layout (390x844)	With the sidebar collapsed, the Kanban import card displays correctly. With it expanded, the column is narrow and the button is clipped; that is the app's existing sidebar behaviour.
✅	Console errors	Only the existing regex pattern error on the project-name input (same on master) and connection-refused messages after the server was stopped.
✅	Backend lint/types/tests	ruff clean; mypy 24 errors on both branch and master (no new); pytest 152 passed / 21 failed, the same 21 test_devserver_security.py failures as on master (master: 144 passed / 21 failed).
⏭️	UI e2e (npm run test:e2e)	All 15 tests failed only because the Playwright Chromium headless shell isn't installed on this machine ('Executable doesn't exist'), and npx playwright install chromium didn't finish within 5 minutes. The UI was exercised with the Playwright browser tools instead.

🧪 Commands run

Command	Result
venv/bin/ruff check .	All checks passed
venv/bin/mypy . (branch vs origin/master worktree)	24 errors on both; no new errors
venv/bin/python test_security.py	ALL TESTS PASSED
venv/bin/python test_security_integration.py	ALL INTEGRATION TESTS PASSED
venv/bin/python -m pytest -q	152 passed, 21 failed (all test_devserver_security.py; master: 144 passed, same 21 failed)
venv/bin/python -m pytest -q test_onboard_project.py	8 passed
npm --prefix ui run build	success (tsc -b && vite build)
npm --prefix ui run lint	0 errors, 6 warnings
uvicorn server.main:app --port 5571 (isolated HOME, no claude on PATH) + python websocket probes	mode validation and spec checks behave as expected
CI=1 VITE_API_PORT=5571 npx playwright test	15 failed: Chromium headless shell not installed on this machine (not a test failure)

No browser screenshots were taken in this round.

_{Posted by cubefarm · merges automatically once GitHub's checks pass}