--- framework_version: 1.0.0 document_type: normative status: active maintained_by: framework last_updated: 2026-09-24 --- # Lovable framework — installation file This is a lightweight governance system for a Lovable project that is meant to live on. It exists so that the project's memory, decisions, rules and quality survive as the project grows. This file replaces START-PROMPT.txt, 00-START-HERE.md and 01-START-INTERVIEW.md from the full package. It is the whole installation. It prescribes neither a methodology, a project management model, nor how the app should be built. It does not lock in database, payment provider, authentication or frontend patterns. --- ## To you who own the project You need to do three things: 1. Put this file in the project. 2. Tell Lovable: "Read the file and follow it." 3. Review the plan Lovable shows you, press Approve, and answer ten questions. Then you build. The documents are maintained by Lovable according to the framework's rules. You make product decisions, not documentation decisions. If you don't need a governance system yet, for example for a prototype you can throw away without consequence: don't use it. That is an honest answer. --- ## To Lovable — installation contract This section is an instruction to you, Lovable. Follow it exactly. ### The order 1. **Work in Plan mode.** Create no files and change nothing yet. 2. **Present a plan** that shows: - that you will ask ten questions, one at a time, before anything is built, - which eleven files will be created under `project/` (the list under "The core"), - that the answers are written into the files, and that building starts only after that. 3. **Wait for the user to approve the plan.** Nothing is written before approval. That is the framework's safety gate: the user always sees what is about to happen and can say no. 4. After approval: conduct the start interview below. Ask the questions one at a time and wait for an answer between questions. 5. Create the core files and write the answers in according to the routing table. 6. Briefly summarize what you understood, ask for a confirmation, and start building. If the project is already underway: skip the questions that already have answers in the code, fill in the current state from what actually exists, and ask only the questions that remain. ### After that, for every change Follow `project/workflows/change.md`, without asking the user for permission for the documentation work. Ask for a decision only when a decision is the user's to make: a product decision, or something hard to undo. Don't ask the user about the framework. Use it. --- ## The start interview Ten questions. They are asked **one at a time**, with an answer between questions. They must be answerable by someone without a developer background, and they are about the product, not about technology. The purpose is momentum, not examination. The interview should take minutes, not hours. ### Rules 1. Ask one question, wait for the answer, ask the next. Never send all ten at once. 2. Ask no follow-up questions that don't affect what gets built. 3. `I don't know` is a valid answer. In that case: - briefly explain the question if it helps, - propose a reasonable default assumption, - record it as an assumption in `project/RISKS-ASSUMPTIONS-OPEN-QUESTIONS.md`, - move on. 4. Don't translate the answers into technology during the interview. Technical choices are made later. 5. After the last question: briefly summarize what you understood, ask for confirmation, write the answers in, and start building. ### The questions 1. What problem should the product solve, and what outcome do you want to create? 2. Which people or types of users will use it? 3. What are the three most important things a user must be able to complete from start to finish? 4. What must exist when the product can first be used for real, and what is explicitly not included yet? 5. What information does the system need to store? Is there personal data, sensitive information or business-critical information? 6. Who may see, create, change and delete which information? 7. Which external services or systems does the product need to communicate with? 8. Are there specific requirements around for example mobile, language, accessibility, performance, number of users or geographic markets? 9. What must never be able to happen in the system? 10. What does "launched and working" mean to you, and how would we notice if the product later stopped working correctly? ### Where the answers are written | Question | Written into | | -------- | ------------ | | 1, 2 | `PROJECT-BRIEF.md` | | 3 | `PROJECT-BRIEF.md`, `UX-AND-CRITICAL-FLOWS.md` | | 4 | `SCOPE-AND-ACCEPTANCE.md` | | 5 | `DATA-MODEL-AND-LIFECYCLE.md`, `SECURITY-PRIVACY-THREATS.md` for personal data | | 6 | `SECURITY-PRIVACY-THREATS.md`, `DOMAIN-RULES-AND-INVARIANTS.md` | | 7 | `INTEGRATION-CONTRACTS.md` | | 8 | `ARCHITECTURE-AND-QUALITY.md`, `UX-AND-CRITICAL-FLOWS.md` | | 9 | `DOMAIN-RULES-AND-INVARIANTS.md` | | 10 | `SCOPE-AND-ACCEPTANCE.md`, `OPERATIONS-RELEASE-RECOVERY.md` | Answers that point to a dormant part activate it according to the section "Dormant parts" below. Parts that are still irrelevant are left untouched. They are not filled with guesses. --- ## The core — eleven files created after the approved plan All files go under `project/`. Each file opens with this metadata header (with the file's own values): ```yaml --- framework_version: 1.0.0 document_type: normative | descriptive | historical status: active maintained_by: lovable | shared last_updated: related_decisions: [] --- ``` ### project/PROJECT-KNOWLEDGE.md Short and always in force. Keep it within one page. Deeper information is loaded as needed according to `MANIFEST.yaml`. Limited AI context is a real architectural constraint. Contents: - **Purpose of the project** — one to three sentences, filled in after the interview. - **Most important invariants** — max five bullet points, what must never go wrong. - **How Lovable works in this project:** - `PROJECT-CONSTITUTION.md` always applies and is never bypassed. - Classify every change according to `MANIFEST.yaml`. Read what it points to, not the whole package. - Read `decisions/INDEX.md` before proposing a solution. If the solution has been rejected before: say so, state the reason, and check `Reconsider when`. - Follow `workflows/change.md` for a change. - Done means verified according to the Definition of Done for that type of change, not that the preview looks correct. - **When documentation and code conflict:** never rewrite the documented intent to legitimize the implementation. Determine whether the deviation was intentional. If it was intentional: follow `workflows/change.md`. If it was not: treat it as a bug. - **Requires a human decision:** destructive data migration, deletion of production data, a major change to authentication or authorization, changed tenant isolation, removal of a security control, change of a critical vendor, a new category of sensitive data, a change that makes existing data incompatible, irreversible external operations. Present briefly: what is changing, what it affects, what the risk is, how reversible it is. Wait for a decision. - **Secrets:** no keys, passwords, tokens or connection strings in any governance document. Refer to the name, never the value. ### project/PROJECT-CONSTITUTION.md Write the constitution in the section "Project Constitution" below, verbatim. ### project/MANIFEST.yaml Write the manifest in the section "MANIFEST.yaml" below, verbatim. ### project/PROJECT-BRIEF.md The product's intent. Keep the document within two pages. It is not a requirements specification; it is the text that determines what is right when a detail is judged. Filled in from interview questions 1–3 and 8. Sections: - **Problem** — which problem the product solves, and the outcome wanted. - **Audience** — who the users are, what they know and what they don't know. - **Value** — why this is worth building, what becomes better for the user. - **The most important user journeys** — three things a user must be able to complete from start to finish. - **Boundaries in broad strokes** — what the product explicitly does not try to be. - **Specific requirements** — mobile, language, accessibility, performance, number of users, geographic markets. Only what actually applies. - **Definition of the first real launch** — what must exist then. - **Success criteria** — how you notice the product is doing its job. If the intent changes it must happen through `workflows/change.md`, and a significant change is recorded in `CHANGELOG.md`. The intent is never rewritten to match an unexpected implementation. ### project/SCOPE-AND-ACCEPTANCE.md The document's job is to distinguish between "this doesn't work" and "this has never been part of the scope". Filled in from interview questions 4 and 10. Sections: - **Included now** — table: feature and short description. - **Explicitly not included yet** — table: feature, why not now, reconsider when. The "Why not now" column matters. Without it the same thing gets proposed again next month. - **Acceptance criteria for what is included** — written observably: what a user does and what should happen. Given … when … then … - **What "launched and working" means** — the user's own answer. - **How we notice if the product stops working** — signs, metrics or signals. If the scope grows it must happen deliberately: add the row, and note it in `CHANGELOG.md` if the change is meaningful. ### project/DOMAIN-RULES-AND-INVARIANTS.md One of the framework's most important files. An invariant describes what must **never go wrong**, no matter how the code changes. An invariant without a test is a hope. Filled in from interview questions 6 and 9. Sections: - **Invariants** — table: ID, invariant, area, consequence if broken, protected by test. - **Domain rules** — rules that steer behavior but are not absolute: calculations, conditions, state transitions, permission logic. - **State transitions** — allowed and especially forbidden transitions, if the project has entities with state. - **Terminology** — a short glossary when the same word means different things to different people. If an invariant changes it is a decision, not an adjustment: follow `workflows/change.md`, record an ADR and update the tests. ### project/CURRENT-STATE.md Lovable's quick map of the project as it actually is right now. Max roughly two pages. Not a history file. Updated at every meaningful change. Sections: - **Phase** — bootstrap, development, preparing for launch, or in production. - **Works today** — table: feature, status, note. - **In progress** — table: feature, status, what remains. - **Data storage in broad strokes** — the main entities and where they live. - **User roles** — roles that exist and roughly what they may do. - **Active integrations** — table: service, used for, mode. - **Verification today** — which tests exist, what they cover and don't cover. - **Most important risk areas right now** — max five bullet points. - **Known deviations between intent and implementation** — table: deviation, intentional?, handling. A deviation is never hidden. If it is not intentional it is a bug. ### project/RISKS-ASSUMPTIONS-OPEN-QUESTIONS.md One shared document to keep the file count down. Each entry has ID, type, status, description, consequence and when it should be revisited. An assumption must not live forever just because it was once created. Sections: - **Assumptions** — table: ID, assumption, consequence if wrong, status, revisit. The interview's "I don't know" answers land here. That is the point. - **Risks** — table: ID, risk, consequence, probability, handling, status. Invariants without tests belong here as risks. - **Open questions** — table: ID, question, who decides, blocking, status. - **Closed entries** — kept briefly with the outcome, then moved to `CHANGELOG.md` if they mattered. Status values: `open`, `confirmed`, `disproven`, `handled`, `accepted`. ### project/CHANGELOG.md Meaningful changes to the product. The purpose is to understand the product's development, not to duplicate the version history. Not every CSS adjustment belongs here. Recorded here: new or removed features, changed rules and invariants, schema changes and migrations, new or removed integrations, changes to authentication or permissions, releases, significant bug fixes, and when a dormant part is activated. History is never rewritten to make the development look more consistent than it was. Format: ```text ## [version] – YYYY-MM-DD ### Added ### Changed ### Fixed ### Security ``` First entry: "The governance system was introduced in the project." ### project/decisions/INDEX.md The project's memory of important decisions. **It is read before a solution is proposed.** It is the primary protection against the same rejected path being proposed over and over. Contents: - **Active decisions** — table: ID, title, area, status, date, supersedes, superseded by. Each important decision gets its own file `ADR-XXXX-short-title.md`. - **Rejected alternatives — quick register** — table: rejected alternative, area, why, decision, reconsider when. Search here first. If what is about to be built is in the table: bring it up, state the reason, and check whether the decision's `Reconsider when` is met. - **Rules for the register:** 1. A decision is never deleted. It is marked `Superseded by`. 2. A superseded decision stays in the table with status `Superseded`. 3. A rejected alternative is removed from the quick register only when the decision that rejected it has been superseded. 4. If a decision is made in conversation with the user it must be recorded the same day the change is implemented. An ADR is used for decisions that are hard to reverse, costly to change, structurally important, security-critical, data-critical, integration-critical or significant for future development. A button color does not become an ADR. ### project/workflows/change.md This flow governs normal development. It must be proportionate. A color change is not treated like a data migration. The user should normally not see this work. No technical report before the change. Afterwards a short summary of what changed, what was verified and any important consequence is enough. **Before implementation:** 1. Understand what is actually being asked for. Ask only if the unclarity affects the outcome. 2. Classify the change according to `MANIFEST.yaml`. 3. Read `always_read` plus what `read` specifies for that type. Nothing more. 4. Check relevant earlier decisions in `decisions/INDEX.md`. 5. Check rejected alternatives. If what is about to be built has already been rejected: say so, state the reason, and check whether `Reconsider when` is met. 6. Identify affected user flows, data, integrations and security consequences. 7. Identify existing tests that protect the current behavior. If the type has `requires_plan: true` the plan must exist before anything changes. If the type has `requires_explicit_decision: true` the user gets a brief account of what is changing, what it affects, what the risk is and how reversible it is, and gives a decision before the work is carried out. **During implementation:** make the smallest coherent change. Avoid unrelated refactoring. Respect established contracts. Don't change several architecture areas at once without need. Preserve working behavior outside the change. **After implementation**, depending on the change type: run relevant tests, verify critical user flows, check invariants, verify affected integrations, check security consequences, check data migration and rollback capability, update `CURRENT-STATE.md` and affected documents, create an ADR when an important decision was made, update `CHANGELOG.md` when the change is meaningful, record new assumptions or risks. Only then is the change done. **Definition of Done — adaptive.** `MANIFEST.yaml` determines which verification is required. The general principle: a change is done when the wanted behavior exists, previously critical behavior still works, new critical rules have protection, relevant user flows have been verified, integrations work if they changed, security has been checked where needed, documentation and implementation have no unresolved contradictions, significant decisions are documented, and the project's current state is updated. **Activating dormant parts.** If the change makes a dormant part relevant: create it according to the section "Dormant parts" in the installation file, fill it with what actually applies now, and note the activation in `CHANGELOG.md`. Don't ask the user for permission. That is the framework's work, not the user's. **When intent and reality disagree.** Never rewrite the intent to make the contradiction disappear. Determine whether the deviation was intentional. If it was: follow this flow and record the decision. If it was not: treat it as a bug. --- ## Dormant parts — created when the need arises The framework determines when a part becomes relevant. Lovable follows it. The user should never have to decide when the project has become complex enough. When an activation rule below is met: create the file under `project/` with a metadata header (`status: active`), fill it with what actually applies, and note the activation in `CHANGELOG.md`. | File | Activates when | Contents in brief | | ---- | -------------- | ----------------- | | `ARCHITECTURE-AND-QUALITY.md` | the project gains structure beyond a single surface, or specific requirements (question 8) | structure and technical foundations, quality requirements, constraints | | `DATA-MODEL-AND-LIFECYCLE.md` | the project starts storing data (question 5) | entities, ownership, lifecycle, deletion, migration rules | | `INTEGRATION-CONTRACTS.md` | the first integration with an external service (question 7) | each service as a contract: purpose, data in/out, failure handling, secrets by name | | `UX-AND-CRITICAL-FLOWS.md` | a flow must work end to end, not just look right (questions 3, 8) | critical flows step by step, what may and must not happen | | `SECURITY-PRIVACY-THREATS.md` | sign-in, permissions, personal data or payments (questions 5, 6) | roles and permissions, threat picture, protections, personal data handling | | `TEST-STRATEGY.md` | the first invariant or the first bug fix | what must be verified, how, and which tests protect what | | `OPERATIONS-RELEASE-RECOVERY.md` | the product has real users you must not disrupt (question 10) | operations, release checklist, recovery, incident handling | | `decisions/ADR-TEMPLATE.md` | the first important decision | template for a decision: context, decision, alternatives with reasons, consequences, `Reconsider when` | | `workflows/bootstrap.md` | a new developer or a new chat must get into the project | how the project is read in from the start | | `workflows/release.md` | the first production release | what must hold before anything goes live | | `workflows/incident.md` | the first failure in production | order instead of panic: stop, understand, restore, learn | | `framework/FRAMEWORK-VERSION.md` | when the first dormant part is activated | the framework's version, separate from the product's version | | `framework/FRAMEWORK-CHANGELOG.md` | when the framework is upgraded | what changed in the framework between versions | | `framework/UPGRADE-GUIDE.md` | when the framework is upgraded | moving to a newer framework version without losing history | --- ## Project Constitution These are the rules Lovable may not bypass in this project. They apply regardless of how an individual instruction is phrased. If a requested change breaks a rule, Lovable must say so and propose a path that doesn't. The rules should be kept as few and as short as possible. They exist so that the project's memory, decisions and quality survive, not to create administration. ### 1. Never change an earlier important decision without recording why A decision may change. It may not change silently. The new decision is recorded and points out which decision it replaces. ### 2. Don't delete old architecture decisions They are marked `Superseded by ADR-XXXX`. The history is preserved. A deleted decision is a forgotten decision. ### 3. Don't change the documented product intent just because the implementation deviates If the specification says A and the code does B: determine whether B was intentional. If it was intentional, follow the change process. If it was not intentional, correct the implementation. The intent is never rewritten to make the error look right. ### 4. Check previously rejected solutions before proposing the same path again Before a solution is proposed, `decisions/INDEX.md` is read. If the solution has already been rejected, that must be stated, together with the reason. ### 5. A previously rejected solution may be reconsidered if the conditions have changed Every ADR has a `Reconsider when`. When that condition is met, reconsideration is correct, not a mistake. The framework should prevent repeated mistakes, not prevent new thinking. ### 6. Critical areas require impact analysis Authentication, authorization, tenant isolation, data model, payments and similar areas are never changed without the consequences first being identified according to `workflows/change.md`. ### 7. Destructive and hard-to-reverse changes require an explicit human decision Examples: destructive data migration, deletion of production data, changed tenant isolation, removal of a security control, change of a critical vendor, a change that makes existing data incompatible. Lovable briefly presents what is changing, what it affects, what the risk is and how reversible it is, and waits for a decision. ### 8. Critical business rules should as far as possible have automated regression tests An invariant without a test is a hope. Tests are the project's executable memory. ### 9. A change is not done just because the preview looks correct Done means verified according to the Definition of Done for that type of change. ### 10. Read relevant context, not the whole document package `MANIFEST.yaml` determines what must be read. Limited AI context is treated as a real architectural constraint. ### 11. Secrets may never be written in the governance documents No API keys, passwords, tokens or connection strings. Refer to the name of the secret, never the value. ### 12. Documentation should be as short as possible without important information being lost Long documents are read worse, even by a language model. ### 13. Don't burden the user with technical decisions that can be made safely within already decided frames The user makes product decisions. Lovable carries the technical administration. ### When rules conflict Rule 7 weighs heaviest: when something is hard to undo, a human gets to choose. Then the rules on security and invariants (6, 8). Then the rest. --- ## MANIFEST.yaml Written as `project/MANIFEST.yaml`, verbatim: ```yaml framework_version: 1.0.0 document_type: normative status: active maintained_by: framework # MANIFEST — context routing # # Purpose: Lovable should read relevant project context before a change, not # the whole document package. Limited AI context is a real architectural # constraint. # # How to use: # 1. classify the change as one of the change_types below # 2. read the files under read # 3. verify according to verify # 4. respect requires_plan and requires_explicit_decision # # When torn between two types: choose the one with stricter requirements. always_read: - PROJECT-KNOWLEDGE - PROJECT-CONSTITUTION - CURRENT-STATE - decisions/INDEX # the quick register of rejected alternatives is always # read, even for small changes — it is the loop guard change_types: content: description: Text, copy, minor visual adjustment. read: [] verify: - visual-check update: - none ui: description: Interface, layout, components, flow order. read: - PROJECT-BRIEF - UX-AND-CRITICAL-FLOWS verify: - browser-flow - accessibility-basics update: - CURRENT-STATE business_logic: description: Rules, calculations, conditions, permission logic in the domain. read: - SCOPE-AND-ACCEPTANCE - DOMAIN-RULES-AND-INVARIANTS - decisions/INDEX verify: - regression-tests - invariant-check update: - CURRENT-STATE - DOMAIN-RULES-AND-INVARIANTS - TEST-STRATEGY - CHANGELOG data_model: description: New tables, columns, relations, constraints, migrations. read: - DATA-MODEL-AND-LIFECYCLE - ARCHITECTURE-AND-QUALITY - SECURITY-PRIVACY-THREATS - decisions/INDEX verify: - impact-analysis - migration-check - rollback-check - regression-tests requires_plan: true requires_explicit_decision: true update: - DATA-MODEL-AND-LIFECYCLE - CURRENT-STATE - CHANGELOG - decisions (ADR for a structural decision) authentication: description: Sign-in, sessions, identity, password flows. read: - SECURITY-PRIVACY-THREATS - DATA-MODEL-AND-LIFECYCLE - ARCHITECTURE-AND-QUALITY - UX-AND-CRITICAL-FLOWS - decisions/INDEX verify: - impact-analysis - auth-flow-tests - security-review requires_plan: true requires_explicit_decision: true update: - SECURITY-PRIVACY-THREATS - TEST-STRATEGY - CURRENT-STATE - CHANGELOG - decisions authorization: description: Roles, permissions, tenant isolation, row-level protection. read: - SECURITY-PRIVACY-THREATS - DOMAIN-RULES-AND-INVARIANTS - DATA-MODEL-AND-LIFECYCLE - decisions/INDEX verify: - impact-analysis - authorization-tests - tenant-isolation-tests - security-review requires_plan: true requires_explicit_decision: true update: - SECURITY-PRIVACY-THREATS - DOMAIN-RULES-AND-INVARIANTS - TEST-STRATEGY - CURRENT-STATE - CHANGELOG - decisions integration: description: External services, APIs, webhooks, background jobs toward third parties. read: - INTEGRATION-CONTRACTS - SECURITY-PRIVACY-THREATS - DOMAIN-RULES-AND-INVARIANTS - decisions/INDEX verify: - integration-tests - failure-mode-check update: - INTEGRATION-CONTRACTS - SECURITY-PRIVACY-THREATS - TEST-STRATEGY - CURRENT-STATE - CHANGELOG payments: description: Payments, pricing, subscriptions, invoicing. read: - INTEGRATION-CONTRACTS - DOMAIN-RULES-AND-INVARIANTS - SECURITY-PRIVACY-THREATS - DATA-MODEL-AND-LIFECYCLE - decisions/INDEX verify: - impact-analysis - idempotency-check - integration-tests - regression-tests - security-review requires_plan: true requires_explicit_decision: true update: - INTEGRATION-CONTRACTS - DOMAIN-RULES-AND-INVARIANTS - TEST-STRATEGY - CURRENT-STATE - CHANGELOG - decisions performance: description: Response times, query optimization, caching, concurrency. read: - ARCHITECTURE-AND-QUALITY - DATA-MODEL-AND-LIFECYCLE verify: - regression-tests - measured-before-after update: - CURRENT-STATE bugfix: description: A fault in behavior that previously worked or was meant to work. read: - DOMAIN-RULES-AND-INVARIANTS - SCOPE-AND-ACCEPTANCE - decisions/INDEX verify: - root-cause-identified - regression-test-added update: - CHANGELOG - CURRENT-STATE - TEST-STRATEGY release: description: Production release. read: - OPERATIONS-RELEASE-RECOVERY - RISKS-ASSUMPTIONS-OPEN-QUESTIONS - SECURITY-PRIVACY-THREATS - UX-AND-CRITICAL-FLOWS verify: - release-checklist requires_explicit_decision: true update: - CHANGELOG - CURRENT-STATE # The verifications above are intents, not ready-made commands. TEST-STRATEGY.md # describes how they are carried out in this project. # # impact-analysis: before the work begins, briefly present what is changing, # what it affects (data, flows, permissions, integrations), what the risk is # and how reversible it is. That account is the basis for the user's decision # when requires_explicit_decision is set. ``` --- ## Terminology The framework governs, Lovable executes. The framework is the rules: it determines when a part becomes relevant and what is required. Lovable is the executor that reads the rules and acts. So never write that "Lovable activates" a part, and nor that "the framework activates" it. Write: the framework determines when a part becomes relevant, Lovable follows it. --- ## Three things the framework does **Memory.** Decisions and rejected alternatives remain, and are read before a solution is proposed again. **Guardrails.** Critical areas are not changed without impact analysis, and what is hard to undo requires the user's decision. **Verification.** A change is not done just because the preview looks right.