How planning and building work
A concept map of Seminova's two-environment model — what each side owns, how documents hand off, and the loop that turns requirements into shipped code.
Two environments
Seminova's planning system runs across two tools with a hard boundary between them. Requirements flow from planning to implementation; shipped code flows back so the next pass starts from what is actually in the repo.
Claude Desktop
Owns
- Planning, alignment, and adversarial review
- Project kickoff and phase planning
- PRDs, roadmap, and shared vocabulary updates
- Implementation plan review before any code lands
Cursor
Owns
- Initializing spinoffs from the template
- Epic implementation plans
- Building and shipping code
- Doc sync after env, scripts, token, or rule-file changes (`/sync-repo-docs` → README, DESIGN.md, `.cursor/rules/README.md`)
Plan, review, build
Work moves in nested loops — a phase loop containing an epic loop of plan, adversarial review, and build. Select or focus a step below to preview which skill and environment own it; click to keep a step selected.
Adversarial review before build is the guardrail — implementation plans are checked against the code and hard constraints so surprises surface in chat, not in a diff.
The documents
A small, stable document set keeps planning and implementation aligned. Each has a clear owner and audience.
| Document | Written by | Read by | Purpose |
|---|---|---|---|
| ROADMAP.md | Claude Desktop | Both | Thin phase stubs — the planning horizon with status and PRD links. |
| docs/prds/ | Claude Desktop | Cursor | Per-phase forward intent — epics, stories, and success criteria. |
| AGENTS.md | Both | Both | Hard constraints, agent workflow gates, merge checklist, and change protocol. |
| LEXICON.md | Both | Both | Shared architectural vocabulary inherited by every spinoff. |
| docs/DOC_RULES.md | Claude Desktop | Both | Authoritative document roles and write discipline. |
Agent-ready conventions
Hard constraints are mechanically enforced so any AI agent inherits the same quality bars on day one. CI fails when these are violated. The full list lives in AGENTS.md.
pnpm only
check:pnpm-onlyNever npm or yarn — one lockfile (pnpm-lock.yaml) for every spinoff.
Primitive-first UI
check:no-shadcn-pkgOwn shadcn/ui components in src/components/ui; never install shadcn as an npm package.
Semantic tokens
check:semantic-tokensThemeable UI color uses semantic tokens from globals.css — no raw hex or numeric Tailwind color scales.
Auth boundary
check:auth-boundaryPublic routes are explicitly allowlisted; all others require a session via the auth proxy.
Admin gate
check:admin-gateAdmin role lives on auth.users app_metadata only — never a profiles column.
SEO base URL
check:seo-base-urlAbsolute site URLs resolve only through getSiteUrl() or metadataBase — no hardcoded origins.
A11y structure
check:a11y-structureEvery route has exactly one h1, meaningful images have alt text, and heading levels do not skip.
A11y contrast
check:a11y-contrastSemantic token foreground pairs in globals.css meet WCAG AA 4.5:1 in both light and dark mode.
Application logging
check:no-raw-consoleApplication code logs through appLog, cliLog, or clientLog — raw console.* only at exempt surfaces.
Go deeper
This page is a concept map. Setup steps, skill references, model guidance, and the full phase-by-phase walkthrough live in the workflow guide on GitHub.