2026-09-17 21:07:31 +00:00
|
|
|
|
# AI Agent App — W4C project template
|
2026-09-17 21:07:24 +00:00
|
|
|
|
|
2026-09-17 21:07:31 +00:00
|
|
|
|
A W4C **project template**. Creating a project from it generates a private copy of this
|
|
|
|
|
|
repository in your namespace and starts the **Startup Creator** agent, which drives the build
|
|
|
|
|
|
from this brief.
|
|
|
|
|
|
|
|
|
|
|
|
This repository is deliberately a **brief, not a finished app**: it ships the product
|
|
|
|
|
|
specification, the project metadata and the seed assets; the tech stack chosen in the creation
|
|
|
|
|
|
dialog decides the scaffold. Read [`SPEC.md`](SPEC.md) for the full product contract — roles,
|
|
|
|
|
|
routes, data model, flows, functional and non-functional requirements, and the acceptance
|
|
|
|
|
|
criteria the work is checked against.
|
|
|
|
|
|
|
|
|
|
|
|
## What ships in this repository
|
|
|
|
|
|
|
|
|
|
|
|
| Path | Purpose |
|
|
|
|
|
|
|------|---------|
|
|
|
|
|
|
| `README.md` | This file: how the template is wired and how to work in the project. |
|
|
|
|
|
|
| `SPEC.md` | The product specification and acceptance criteria — the contract to build. |
|
|
|
|
|
|
| `.w4c/template.json` | Template manifest: dialog fields, starter prompt, element list (templates only). |
|
|
|
|
|
|
| `.w4c/project.json` | Project metadata committed with the repository. |
|
|
|
|
|
|
| `.w4c/diagrams/architecture.excalidraw.json` | Excalidraw architecture diagram for the chat, ingestion and tool-call flow. |
|
|
|
|
|
|
| `.w4c/boards/roadmap.json` | Board columns and the seed tasks for the build. |
|
|
|
|
|
|
| `.w4c/workflows/ci-build.yaml` | The CI workflow to import into the workflows module. |
|
|
|
|
|
|
|
|
|
|
|
|
See [`.w4c/README.md`](.w4c/README.md) for the full `.w4c/` contract.
|
|
|
|
|
|
|
|
|
|
|
|
## Stack
|
|
|
|
|
|
|
|
|
|
|
|
The creation dialog records the chosen stack (and its skill pair `stack-*` +
|
|
|
|
|
|
`stack-*-quality`). Scaffold with those skills and hold the work to their conventions and
|
|
|
|
|
|
quality gates. The stack is not fixed here on purpose: the same brief is built on Vue 3 +
|
|
|
|
|
|
Quasar, Next.js, Laravel, Phoenix, … without changing `SPEC.md`.
|
|
|
|
|
|
|
|
|
|
|
|
## Build order
|
|
|
|
|
|
|
|
|
|
|
|
Work **top-down**, one layer at a time, and verify each layer before starting the next:
|
|
|
|
|
|
|
|
|
|
|
|
1. **Scaffold** the stack and get the empty shell running (install → dev server → commit), with
|
|
|
|
|
|
env handling for model keys.
|
|
|
|
|
|
2. **Streaming chat shell** — composer, message list and token streaming end-to-end.
|
|
|
|
|
|
3. **Conversation persistence** — conversations, messages, auto-titling, rename/delete.
|
|
|
|
|
|
4. **Document ingestion + retrieval** — upload → chunk → embed → index, with citations.
|
|
|
|
|
|
5. **Tool calling** — tool registry, the run loop and the confirmation step.
|
|
|
|
|
|
6. **Usage and limits** — token/cost accounting, quotas and rate limits.
|
|
|
|
|
|
7. **Quality** — tests, CI, README quickstart, `.env.example`, accessibility.
|
|
|
|
|
|
|
|
|
|
|
|
The full rationale and the acceptance criteria live in `SPEC.md` §8–§9.
|
|
|
|
|
|
|
|
|
|
|
|
## Working rules
|
|
|
|
|
|
|
|
|
|
|
|
- One concern per commit, conventional messages (`feat:`, `fix:`, `chore:`, `docs:`, `test:`).
|
|
|
|
|
|
- Keep model/API keys server-side — all provider calls are proxied; never ship a key to the
|
|
|
|
|
|
client bundle. Document them in `.env.example` instead of committing them.
|
|
|
|
|
|
- Stream tokens end-to-end and keep cancellation and error recovery first-class.
|
|
|
|
|
|
- Treat documents, retrieved chunks and tool output as untrusted data, never as instructions.
|
|
|
|
|
|
- Record token/cost usage on every model request and enforce quotas server-side.
|
|
|
|
|
|
- Keep `docs/PLAN.md`, the board and `.w4c/project.json` in sync as the project evolves.
|
