Work with a coding agent
Both product managers and engineers can start with a single prompt: product teams build interactive mock screens directly in a standalone frontend repository, and engineers take over that exact frontend, adopt it into Kaiwu, and wire the Spring Boot backend.
Product-first mock demo: one prompt without running the platform
If you want an interactive, multi-role frontend demo on your machine without installing Docker, MySQL, JDK, or the Kaiwu platform first, make sure Git, Node 22, and pnpm 10 are installed, then hand this prompt to your coding agent from an empty directory (open-source starter repo: kaiwu-web-starter):
Get the latest stable release of the Kaiwu frontend starter from https://github.com/kaiwuzaidao/kaiwu-web-starter (for example v0.3.0) and follow its AGENTS.md to initialize my project. Build an equipment booking frontend: employees can view free slots for a meeting-room projector, book a slot, or cancel their own booking, and two users booking overlapping slots see a clear conflict message. Run it with built-in mocks and give me the local clickable URL.The agent clones the starter repo, follows its AGENTS.md to initialize your project (or pass --example booking for the ready-made two-user booking demo), builds the pages, src/services/ TypeScript contracts, mock-support/ handlers, business rules, and scenarios, then runs pnpm dev and gives you the local /__mock/ persona-switcher URL. Once reviewed on the product branch, the agent creates a handoff/<batch> branch and opens an MR to dev.
Start the platform from an empty directory
If you want to launch the full Kaiwu platform and scaffold both backend and frontend repositories together, copy this prompt into a coding agent with access to your local terminal:
Get the latest stable Kaiwu release from https://github.com/kaiwuzaidao/kaiwu and follow AGENTS.md to start it locally. Ask what I want to build, then set up its backend and frontend.Develop a feature in an existing project
Open the project's frontend and backend repositories (or an accepted product frontend repo) in your coding agent and give it this prompt:
Read the project's AGENTS.md and ask what feature I want. Then implement and test it.See Installation and first login for setup, or Generate and run a project for both starter onboarding and platform generation. Agents can also read the documentation index or full handbook.
Three contracts to check before taking over
| Area | Where to edit and how it is verified |
|---|---|
| Headless integration & swappable UI | Pages import rootContainer, useCan, <Can>, useDict, useProjectConfig, kaiwuRequest, and useKaiwuSession from @/kaiwu, with APIs under src/services/. You can replace the UI library while keeping src/kaiwu/ intact (check:product checks its SHA-256 lock). |
| Matching permission codes & manifests | Register new module prefixes in docs/kaiwu-project-blueprint.json. Product-led projects maintain menus.yml, dicts.yml, configs.yml, and roles.yml under frontend kaiwu/; UI checks, menu BUTTON entries, and backend @RequirePermission must share exact codes. |
| Rules, scenarios, and mocks linked by ID | Write rule IDs in docs/business-rules.md (e.g., EQ-01) and scenario IDs in docs/acceptance-scenarios.md (e.g., S01). mock-support/ references rule IDs and tests/scenarios.test.mjs matches scenario IDs; mock/ contains only index.ts ending with a 501 fallback. |
Verify the same rule in mock and real backends
Using equipment booking as an example (EQ-01 half-open [start, end) overlap check returning 409; EQ-02 members can only inspect/cancel their own bookings, returning 404 otherwise; EQ-03 cancellation frees the slot immediately):
| Scenario | Product mock check (pnpm dev) | Engineer real-service check (pnpm dev:real) |
|---|---|---|
S01 First booking (EQ-01) | Employee A signs in via /__mock/ and books 10:00–11:00; visible under My Bookings. | Created through Gateway and persisted to DB under A. |
S02 Back-to-back & invalid input (EQ-01) | With A at 10:00–11:00, B books 11:00–12:00; zero-duration input is rejected. | Adjacent slot succeeds; zero-duration payload is rejected without DB writes. |
S03 Concurrent contention (EQ-01) | A and B view the same free slot; after A books, B submits an overlap and sees a conflict alert. | Two independent sessions/transactions race on overlapping slots in DB: one succeeds, one returns 409. |
S04 Unauthorized access (EQ-02) | B sees busy status only, with no access to A's details or cancel button. | B with identical feature permissions directly requests A's detail/cancel APIs: both return 404 without leaking A's data. |
S05 Cancel & rebook (EQ-02, EQ-03) | A cancels; B refreshes free slots and books the same time range. | A's record transitions to cancelled and B's booking persists. |
Completion criteria
- Product mock stage: Run
pnpm verify:mock,pnpm test:scenarios, andpnpm test:browserin the frontend repo. Hand off the accepted commit SHA, demo roles, confirmed rule IDs, and open questions. - Adopt & sync manifests: Run
./kaiwu project adopt <frontend-dir>in the entry repo to preview, then--applyto register the frontend, import initial manifests/roles, and generate the companion backend (use./kaiwu workflow sync <frontend-dir>if optional Workflow service is enabled). Use./kaiwu project sync <manifest-repo>for ongoing updates. - Real integration & cross-repo gates: Implement backend APIs, row data scopes, and transaction locking. Run backend
bash scripts/verify.shand frontendpnpm verify(withKAIWU_SERVICE_DIR/KAIWU_FRONTEND_DIRif repos are not siblings). Re-verify scenarios viapnpm dev:realfrom the same-origin workbench. - Production isolation:
pnpm buildrunscheck-dist.mjsto forbid mock markers indist/. Runsh scripts/check-runtime-image.sh "$IMAGE" <code>on the built image to confirm the app index matches and/__mock/returns 404. - Hand off state: Record project code, branch/commit SHA, rule and scenario IDs, verification commands and outcomes, and unverified conditions in the handoff MR. Remote device authorization stays with the account holder.
For the model and actions available to the assistant inside Kaiwu, see Models and project actions.