Fullstack Prod

Fullstack Prod

Orchestrate complete full-stack products. Prefer depth of process over speed of scaffolding.

Hard rules

1. Do not scaffold or write product code until intake is complete and contradictions are resolved with the user.
2. Verify package/API currency against official docs before installing. Never invent APIs, CLI flags, or config keys.
3. Pin versions of critical dependencies; prefer maintained defaults from the stack playbook.
4. TDD for behavior: failing test → implement → refactor. Skip only if the user explicitly waives; record the waiver in an ADR.
5. Modular monolith by default: one deployable app (or one primary backend + one web UI) with clear internal modules and boundaries. Do not split into microservices, extra deployables, or distributed “for scale” unless the user explicitly requires it — then record the waiver in an ADR.
6. i18n required: every app supports locales and multiple languages (message catalogs, locale-aware routing or equivalent, no hardcoded user-facing copy in components). Confirm default + additional locales with the user; ship at least two locales unless they explicitly waive — then ADR.
7. Dark and light modes required: every UI supports theme toggle (or system + manual override) via design tokens/CSS variables — not one-off color swaps. Both themes must meet contrast for primary UI.
8. Responsive required: every product must work on mobile, tablet, and desktop. Layouts fluid (not desktop-only with horizontal scroll); touch targets usable on small screens; verify primary flows at ~375px and ≥1280px before calling a slice done.
9. Vertical slices only: each user flow ships API + UI + tests + polish together. No big-bang backend-then-frontend.
10. After each slice: tests, typecheck/lint, and the slice’s happy + failure paths must pass before the next slice.
11. AI docs are required in every product (see checklists/ai-docs.md). Keep them short and navigational — fixed kit, not essays.
12. Update agent docs whenever structure, commands, or conventions change.

Progressive disclosure

Read these when needed (one level deep):

Phase 1 — Intake (block coding)

Read checklists/intake.md. Ask the required questions. Do not assume stack, auth, or scope.

If the user is vague, ask follow-ups until these are clear:

• Product one-liner, primary users, core jobs-to-be-done
• Must-have flows (happy + failure)
• Stack (or request a recommendation with rationale)
• Auth, data store, hosting targets
• Default locale + which additional languages to ship first
• MVP vs production bar for this build
• Constraints, brand/design direction, non-goals

Phase 2 — Critique and resolve

Before any plan approval:

1. Propose Must / Should / Could features (prioritized; not a laundry list).
2. Run a short premortem: what would make this product fail?
3. Flag contradictions, missing entities, circular flows, conflicting constraints (e.g. offline-first + heavy realtime).
4. Recommend modifications that simplify or de-risk the product.

Stop and resolve with the user. Do not proceed until contradictions and Must-scope are agreed.

Phase 3 — Architecture plan

Produce a concise plan the user can confirm:

• Modular monolith shape: modules, boundaries, and how they communicate in-process (not via a service mesh)
• Domain model (entities, relationships, states)
• Permissions / tenancy model
• Module boundaries (feature modules + UI / domain / data / infra)
• i18n approach (library, catalog layout, locale detection/switching)
• Theming approach (tokens, light/dark, persistence, system preference)
• API contract approach (typed schemas, OpenAPI, etc.)
• Ordered vertical slices (smallest useful path first)
• Product-specific Definition of Done (inherit checklists/definition-of-done.md)

Lock early decisions that are expensive to change: auth model, multi-tenancy, locales, billing. Prefer extracting a service later from a clean module boundary over starting distributed. Wire i18n and theme tokens into the first UI slice — do not bolt them on at the end.

Phase 4 — Stack playbook

1. Open the matching stacks/*.md, or fill stacks/_template.md from current official docs.
2. Confirm packages and versions before scaffolding.
3. Scaffold only what the first slice needs; avoid unused boilerplate.

Phase 5 — Build (vertical TDD slices)

For each slice, in order:

1. Write/adjust failing tests for the behavior.
2. Implement domain + data + API + UI for that flow.
3. Apply checklists/ui-ux.md for any user-facing surface (loading, empty, error, success).
4. Refactor while green.
5. Verify: test suite for the slice, typecheck, lint, manual/critical-path exercise of happy + failure paths.
6. Only then start the next slice.

Prefer contract-first boundaries (shared types / OpenAPI / Zod / schema) before wiring UI to API.

Phase 6 — AI-first documentation

Generate the fixed kit in checklists/ai-docs.md early enough that later slices stay consistent — at latest before calling the build done. Minimum:

• AGENTS.md
• .cursor/rules (or project skills)
• docs/architecture.md, docs/map.md, docs/decisions/ ADRs
• API contract as source of truth
• .env.example + seed/demo path

Phase 7 — Final gate

Before declaring done:

1. Pass checklists/definition-of-done.md
2. Pass checklists/security.md
3. Refresh AGENTS.md / docs/map.md if the tree or commands changed
4. Summarize for the user: what shipped, how to run/test, known non-goals, next Should/Could items

Output style during intake

• Ask in focused batches (not one giant wall of questions).
• When recommending, use Must / Should / Could labels.
• When flagging issues, state the conflict, why it matters, and a proposed resolution.
• Think thoroughly; prefer clarifying over guessing.