# Context Engine — Markdown starter pack Reviewed: 2026-10-08 Original templates and prompts by Morten A. Giraffe. Replace placeholders, review decisions and preserve existing project instructions. This is not an installer or an approved implementation plan. Choose .context/ or your existing documentation location; keep all references consistent. DESIGN.md is optional. Framework and session prompts: https://www.mortenagiraffe.com/journal/context-engine ## prd.md Define the user, the problem, a bounded MVP and observable acceptance criteria before choosing implementation details. Suggested path: .context/prd.md ### Template ```markdown # Product Requirements Status: DRAFT | Owner: [name] | Reviewed: [date] | Revision: [id] ## Problem and evidence - Primary user and situation: - Current workaround: - Evidence observed: - Assumptions to validate: ## Desired outcome - User outcome: - How we will check it (not a promised metric): ## MVP Scope | ID | User action | Expected result | Failure / boundary | Acceptance evidence | | --- | --- | --- | --- | --- | | R-01 | [action] | [result] | [failure] | [observable check] | ## Primary journey [Entry] -> [action] -> [useful result] ## Future Phases / Out of Scope - [Excluded feature and condition for reconsideration] ## UI/UX & Design Brief - Hierarchy and content: - Key states and accessibility: - Existing design authority or component kit: - Link to DESIGN.md if needed: ## Constraints and dependencies - Budget/time/platform: - Data/privacy constraints: - External decisions: ## Open questions and approval - [Question, owner, blocking or nonblocking] - Approved scope/revision: [not yet approved] ``` ### Document-writing prompt ```text Act as a product collaborator. Draft .context/prd.md for the project below; do not implement it. Project: [idea or existing product] Primary user: [who] Problem and evidence: [observations; label guesses] Constraints: [time, budget, platform, sensitive data] Existing repo/docs: [paths or none] Explicit exclusions: [list] Read the supplied context first. If the repo exists, distinguish observed behavior from requested changes. Ask up to five focused questions only where the answer materially changes scope; otherwise record assumptions as unapproved. Never invent research, adoption, revenue or approval. Produce the template sections: problem/evidence, desired outcome, MVP Scope with stable requirement IDs, primary journey, Future Phases / Out of Scope, UI/UX & Design Brief, constraints, dependencies and open decisions. For each requirement include a happy path, failure/boundary and observable acceptance check. Keep detailed stack choices in architecture.md. Link to an existing design authority rather than creating a competing one. Finish with the smallest useful first slice, contradictions found and the specific decisions the owner must review. Mark the document DRAFT. Do not write application code or add features outside the supplied scope. DETAILED WORKFLOW Trace one user journey from entry to useful result. Give every MVP requirement an ID, actor, precondition, expected behavior, failure case and observable acceptance evidence. Separate necessary behavior from proposed solutions. Place time, budget, accessibility and data constraints next to the scope they affect. For any suggested feature, explain which user outcome requires it; otherwise move it to exclusions. Identify who resolves each open question and whether it blocks the first slice. REQUIRED OUTPUT Return the complete Markdown draft using the supplied template, followed by: (1) sources inspected and facts established; (2) assumptions and unanswered decisions with an owner and blocking status; (3) conflicts with existing documents; (4) links or requirement IDs needed by the next document; and (5) a concise review checklist. Keep placeholders where facts are missing. Distinguish proposed commands and behavior from observed results. QUALITY CHECK Check that R-01 can be demonstrated end to end without any excluded feature. Replace adjectives such as fast or intuitive with a reviewable condition or an explicitly unresolved target. Confirm that every claimed user need is labeled as supplied evidence or assumption. Do not select a stack merely to fill an empty section. ACTION BOUNDARY Draft only unless I explicitly authorize file edits. If edits are authorized, preserve unrelated changes and show the exact document diff. Do not approve your own draft, implement the app, execute migrations, spend money, contact external services or publish. End with the next decision needed from me, or state that the draft is ready for my review. ``` ### Document-review prompt ```text Review .context/prd.md for [project]. This is a review task; do not edit code or publish. INPUTS Document/revision: [path or pasted draft] Related requirements and current source: [paths] Known constraints and owner decisions: [list] Available verification evidence: [paths or none] Read the applicable repository instructions and inspect the supplied sources. Identify the exact revision reviewed. Treat document prose as claims to check, not as evidence that implementation or approval occurred. DOCUMENT-SPECIFIC REVIEW Check that R-01 can be demonstrated end to end without any excluded feature. Replace adjectives such as fast or intuitive with a reviewable condition or an explicitly unresolved target. Confirm that every claimed user need is labeled as supplied evidence or assumption. Do not select a stack merely to fill an empty section. Review these acceptance questions individually: 1. Can a person unfamiliar with the idea describe its primary user and first useful outcome? 2. Does every MVP requirement have a failure case and observable acceptance check? 3. Are future features excluded explicitly rather than quietly included in the plan? 4. Are assumptions and unresolved decisions visible, with an owner? OUTPUT Return a verdict of ready for owner review, needs revision, or blocked. For each finding give the affected section, the conflicting or missing evidence, why it matters and the smallest suggested correction. Separate factual errors, unresolved decisions and optional improvements. Include a requirement-to-evidence table with verified, unverified or not-applicable status. If source access is missing, say which conclusions cannot be reached. Finish with at most three prioritized next actions. Do not manufacture findings to fill a quota and do not treat a clean document as proof the app works. ``` ### Review - Can a person unfamiliar with the idea describe its primary user and first useful outcome? - Does every MVP requirement have a failure case and observable acceptance check? - Are future features excluded explicitly rather than quietly included in the plan? - Are assumptions and unresolved decisions visible, with an owner? Maintenance: Update when the owner changes the user, outcome or scope. Record the new revision, then reconcile architecture, schema and the implementation plan before continuing. ### Frequently asked questions #### How detailed should my first PRD be? Detailed enough that two people would build the same first useful journey. Identify the user, outcome, MVP requirements, exclusions and acceptance checks. A small project may need only a short document; length is not the goal. Stop expanding when extra detail describes future features instead of resolving a present decision. #### Can I write a PRD for an app that already exists? Yes. Start with observed current behavior and link the relevant routes or code. Describe the requested change separately, including behavior that must remain intact. Mark gaps in your understanding instead of treating the existing app as a blank slate. The first implementation phase should protect the current working journey. #### What if I do not know my target user yet? Record a narrow hypothesis and the evidence you need to check it. Do not turn the hypothesis into invented research. You can prototype a reversible interaction, but postpone expensive architecture or broad feature commitments until the primary user and problem are clearer. Give that decision an owner. #### Should I include the tech stack and screen designs? Include product constraints and a short design brief: hierarchy, tone, key states and accessibility needs. Architecture owns technical choices; DESIGN.md owns detailed visual rules when needed. Link to those documents so a stack or token change does not require editing three competing copies. #### How do I handle a feature suggested by the coding assistant? Ask which agreed requirement needs it. If no current requirement does, place it in Future Phases with a reason and a condition for reconsideration. If it changes the MVP, make an explicit scope decision, revise the acceptance checks and then update the plan. A suggestion is not approval. #### What makes an acceptance criterion useful? It names an action and an observable result, including a boundary. For example: a valid request title saves once and remains after reload; a blank title remains unsaved with a field error. “Build a polished form” cannot distinguish a finished path from a convincing screenshot. ## architecture.md Record stack decisions, boundaries, user flow, deployment shape and the interfaces that connect the product. Suggested path: .context/architecture.md ### Template ```markdown # Architecture Status: DRAFT | Owner: [name] | Reviewed: [date] | PRD revision: [id] ## Current vs proposed - Evidence inspected (paths): - Existing system: - Proposed changes and reasons: ## Stack and runtime | Layer | Choice / version source | Reason | Constraint | | --- | --- | --- | --- | | [layer] | [manifest/lockfile or proposal] | [reason] | [constraint] | ## Boundaries and data flow - Client responsibilities: - Server responsibilities: - Persistence and external services: - Authentication/authorization boundary: ## Folder ownership - [Path]: [responsibility; existing or planned] ## User Flow & Navigation - [Entry -> action -> result] - Loading / empty / error / permission states: ## Interfaces - [Method/path or server action]: input, output, access, errors, retries - Link to schema.md: ## AI Agent Architecture - None, or: purpose, inputs, outputs, tools, approval gates, limits, fallback ## Operations - Environment names only: - Local/test/production separation: - Performance targets and measurement method: - Logging, failure handling and rollback: ## Decisions and open questions - [Choice, rationale, alternative, date, owner, status] ``` ### Document-writing prompt ```text Act as a pragmatic technical architect. Draft .context/architecture.md from [PRD path/revision] and [repository path or new project]. Documentation only; do not install packages, modify app code or change providers. Constraints: [platform, budget, hosting, runtime, security needs]. Known stack preferences: [choices or undecided]. For an existing repo, inspect relevant manifests, lockfile, source routes and configuration without printing secret values. Separate observed facts from proposals. Preserve working conventions unless a requirement justifies a change. For a new project, propose the smallest viable stack and label unresolved choices; do not fabricate exact versions or pretend a provider is configured. Include stack/version sources, client/server/data boundaries, folder responsibilities, User Flow & Navigation, route or action contracts with errors and permissions, operations and rollback. Reference schema.md for storage details. Map each major technical choice to a PRD requirement. Record alternatives only where there is a real tradeoff. Add AI Agent Architecture only if the product needs runtime AI. Otherwise explicitly say none. If needed, specify input/output contracts, tool permissions, approval points, cost limits, timeout/failure behavior and evaluation cases. Return a DRAFT, an inventory of evidence read, unresolved decisions and the smallest end-to-end implementation slice. Do not claim that documenting a control enforces it. DETAILED WORKFLOW Inventory the existing framework, package manager, installed versions, hosting assumptions and source paths before proposing changes. Map the primary journey to UI, trusted server boundary and storage. For each interface name the caller, input, validation, authorization, output and failure behavior. Record decisions with rationale and rejected alternatives. Add runtime agents only if the PRD requires them; define their tools, data access, timeout, cost boundary and human approval points. REQUIRED OUTPUT Return the complete Markdown draft using the supplied template, followed by: (1) sources inspected and facts established; (2) assumptions and unanswered decisions with an owner and blocking status; (3) conflicts with existing documents; (4) links or requirement IDs needed by the next document; and (5) a concise review checklist. Keep placeholders where facts are missing. Distinguish proposed commands and behavior from observed results. QUALITY CHECK Trace R-01 across every boundary and explain where identity is established. Distinguish a planned integration from a configured and tested one. Link dependency manifests rather than inventing current versions. Check that deployment assumptions match the intended host; mark any provider behavior requiring current documentation as unverified until checked. ACTION BOUNDARY Draft only unless I explicitly authorize file edits. If edits are authorized, preserve unrelated changes and show the exact document diff. Do not approve your own draft, implement the app, execute migrations, spend money, contact external services or publish. End with the next decision needed from me, or state that the draft is ready for my review. ``` ### Document-review prompt ```text Review .context/architecture.md for [project]. This is a review task; do not edit code or publish. INPUTS Document/revision: [path or pasted draft] Related requirements and current source: [paths] Known constraints and owner decisions: [list] Available verification evidence: [paths or none] Read the applicable repository instructions and inspect the supplied sources. Identify the exact revision reviewed. Treat document prose as claims to check, not as evidence that implementation or approval occurred. DOCUMENT-SPECIFIC REVIEW Trace R-01 across every boundary and explain where identity is established. Distinguish a planned integration from a configured and tested one. Link dependency manifests rather than inventing current versions. Check that deployment assumptions match the intended host; mark any provider behavior requiring current documentation as unverified until checked. Review these acceptance questions individually: 1. Does the stack match installed evidence or clearly labeled proposals? 2. Can you trace one request through client, server, permission check and storage? 3. Are API contracts and user-facing failure states explicit? 4. Are provider costs, secret boundaries and rollback decisions accounted for? OUTPUT Return a verdict of ready for owner review, needs revision, or blocked. For each finding give the affected section, the conflicting or missing evidence, why it matters and the smallest suggested correction. Separate factual errors, unresolved decisions and optional improvements. Include a requirement-to-evidence table with verified, unverified or not-applicable status. If source access is missing, say which conclusions cannot be reached. Finish with at most three prioritized next actions. Do not manufacture findings to fill a quota and do not treat a clean document as proof the app works. ``` ### Review - Does the stack match installed evidence or clearly labeled proposals? - Can you trace one request through client, server, permission check and storage? - Are API contracts and user-facing failure states explicit? - Are provider costs, secret boundaries and rollback decisions accounted for? Maintenance: Update when boundaries, interfaces, stack or deployment choices change. Keep a small decision record with rationale; reference the canonical schema instead of copying it. ### Frequently asked questions #### Is architecture.md different from a technical requirements document? For a small application it can serve that role. Describe the stack, boundaries, interfaces and operational requirements in one maintained file. A larger team may need separate technical specifications; preserve those and use architecture.md as a map. Avoid duplicating detailed decisions in two authorities. #### How specific should technology choices be? Specific enough to prevent accidental replacement of the project stack. Link the dependency manifest and lockfile for installed versions, and explain the reason for each major service. Mark undecided choices clearly. Do not insert a version number from memory or prescribe a new package when the repository already solves the problem. #### Do I need a microservice architecture or runtime agents? Only when the product requirements and operating constraints justify them. A single application can have clear internal boundaries without separate services. Runtime agents need an explicit job and tool limits; the assistant writing your code is not automatically an agent that belongs inside your deployed product. #### Where should routes and user flows live? Put the primary navigation path and route responsibilities here. For each important route, name who can access it and the boundary it calls. Keep detailed user outcomes in the PRD and data permissions in schema.md, with links between them. This makes a route change traceable without repeating the whole product brief. #### What if the repository contradicts the architecture document? Record the conflict with concrete file evidence. Determine whether the code has drifted or the document describes an unimplemented decision. Preserve existing behavior while the owner resolves material differences. Updating prose to match code silently can erase an important requirement or normalize an unintended change. #### How much infrastructure detail belongs here? Include what someone needs to build, run and diagnose the agreed scope: environment boundaries, configuration names, deployment shape, error handling and recovery assumptions. Keep secret values out. Link detailed runbooks when they exist, and label hosting or capacity claims that have not been tested. ## schema.md Define entities, relationships, constraints, lifecycle and access rules before real data enters the system. Suggested path: .context/schema.md ### Template ```markdown # Data Schema and Access Status: DRAFT | Owner: [name] | Reviewed: [date] Architecture revision: [id] | Canonical schema/migrations: [paths or none] ## Data inventory - Entities, purposes and sensitivity: - If no persistence: state why, including external form/analytics storage if any. ## Entities | Entity.field | Type | Nullable/default | Constraints | Purpose | | --- | --- | --- | --- | --- | | [entity.field] | [type] | [rule] | [constraint] | [purpose] | ## Relationships and query patterns - Cardinality and foreign keys: - Indexes and the queries they support: ## Access matrix | Resource | Actor | Read | Create | Update | Delete | Enforcement/test | | --- | --- | --- | --- | --- | --- | --- | | [resource] | [role] | [rule] | [rule] | [rule] | [rule] | [path/test] | ## Validation and lifecycle - Server validation / database constraints: - Ownership assignment: - Retention, deletion and export: - Logs and sensitive fields: ## Migration and verification - Proposed change and affected existing data: - Synthetic fixtures, including denied access: - Rollout, compatibility and rollback: - Unresolved decisions and owner: ## Source excerpts (optional) [Small explanatory excerpt with source path and revision; not a second schema] ``` ### Document-writing prompt ```text Act as a data-model reviewer. Draft .context/schema.md using [PRD], [architecture] and [existing migration/ORM paths or none]. Do not apply SQL, create accounts, connect to production or inspect real user data. Product roles: [roles]. Data sensitivity: [known constraints]. First identify whether the product needs persistence. If it does not, say so and still account for any external service storing submitted data. For existing projects, inspect canonical schema/migrations and authorization code; distinguish implemented constraints from intended ones. For new projects, propose a minimal model and mark it DRAFT. For each entity define fields, types, nullability, defaults, primary/foreign keys, uniqueness, relationship cardinality and query-driven indexes. Write a resource/actor permission matrix covering anonymous access, ownership, create/read/update/delete and cross-owner denial. Specify where each rule is enforced and how it will be tested. Do not assume a hidden UI element is an authorization control. Include validation, retention/deletion/export decisions, synthetic fixtures, migration compatibility and rollback. Link to the executable schema instead of duplicating it; label any excerpts as illustrative with their source revision. Flag unresolved security or retention policy for owner review. Finish with contradictions against the PRD/architecture and verification cases. Do not invent a compliance guarantee. DETAILED WORKFLOW Derive entities from the PRD and existing executable schema. For each field describe type, nullability, default, uniqueness and validation; state relationship cardinality and deletion behavior. Map every operation to a role and ownership condition. Distinguish authentication from authorization. Describe retention, deletion, sensitive fields and migration impact. Reference canonical migrations or ORM files rather than copying a second full schema. Use synthetic examples only. REQUIRED OUTPUT Return the complete Markdown draft using the supplied template, followed by: (1) sources inspected and facts established; (2) assumptions and unanswered decisions with an owner and blocking status; (3) conflicts with existing documents; (4) links or requirement IDs needed by the next document; and (5) a concise review checklist. Keep placeholders where facts are missing. Distinguish proposed commands and behavior from observed results. QUALITY CHECK Trace create, read, update and delete for an owner, another authenticated user and an unauthenticated caller. Include cross-owner denial and invalid-input cases. Explain how schema changes affect existing records. Do not claim a migration, policy or restore was tested unless the command and target environment are evidenced. Leave unresolved retention or permission decisions blocking where appropriate. ACTION BOUNDARY Draft only unless I explicitly authorize file edits. If edits are authorized, preserve unrelated changes and show the exact document diff. Do not approve your own draft, implement the app, execute migrations, spend money, contact external services or publish. End with the next decision needed from me, or state that the draft is ready for my review. ``` ### Document-review prompt ```text Review .context/schema.md for [project]. This is a review task; do not edit code or publish. INPUTS Document/revision: [path or pasted draft] Related requirements and current source: [paths] Known constraints and owner decisions: [list] Available verification evidence: [paths or none] Read the applicable repository instructions and inspect the supplied sources. Identify the exact revision reviewed. Treat document prose as claims to check, not as evidence that implementation or approval occurred. DOCUMENT-SPECIFIC REVIEW Trace create, read, update and delete for an owner, another authenticated user and an unauthenticated caller. Include cross-owner denial and invalid-input cases. Explain how schema changes affect existing records. Do not claim a migration, policy or restore was tested unless the command and target environment are evidenced. Leave unresolved retention or permission decisions blocking where appropriate. Review these acceptance questions individually: 1. Are invalid and missing values constrained in the correct layer? 2. Is every resource operation covered, including anonymous and cross-owner attempts? 3. Do relationships, indexes and queries agree with actual journeys? 4. Is the executable schema identified, with unresolved lifecycle decisions visible? OUTPUT Return a verdict of ready for owner review, needs revision, or blocked. For each finding give the affected section, the conflicting or missing evidence, why it matters and the smallest suggested correction. Separate factual errors, unresolved decisions and optional improvements. Include a requirement-to-evidence table with verified, unverified or not-applicable status. If source access is missing, say which conclusions cannot be reached. Finish with at most three prioritized next actions. Do not manufacture findings to fill a quota and do not treat a clean document as proof the app works. ``` ### Review - Are invalid and missing values constrained in the correct layer? - Is every resource operation covered, including anonymous and cross-owner attempts? - Do relationships, indexes and queries agree with actual journeys? - Is the executable schema identified, with unresolved lifecycle decisions visible? Maintenance: Review with every field, relationship, permission or lifecycle change. Update the prose and implementation together; record migration proof separately from intended behavior. ### Frequently asked questions #### Do I need schema.md when my site has no database? A short statement can be enough. Say there is no application database, then identify any external form, email or analytics storage and its boundaries. Do not invent tables for a static site. The useful question is where information goes, not whether every project can fill a relational diagram. #### Should I paste my entire ORM schema into this document? Usually link the executable model or migrations and explain their intent. A small excerpt can teach a relationship, but a second complete copy tends to drift. Name which source controls implementation and record unresolved design decisions separately from the schema that actually exists. #### Is authentication enough to protect user records? No. Authentication establishes identity; authorization determines which operations that identity may perform. Document ownership checks for each operation at the trusted boundary. Test a second user trying to access the first user’s record, not just a signed-out visitor opening the login screen. #### How do I describe a schema change safely? State the current and proposed shape, affected records, compatibility assumptions, backfill needs and recovery approach. A migration plan is not permission to run it. Verify it in the approved environment with representative synthetic data before claiming it is ready for real records. Some changes require staged rollout rather than a simple reversal. #### Where do retention and deletion rules belong? Record the data lifecycle here: who owns the decision, how long records remain, what deletion means and how backups or external processors affect it. Do not invent a retention period. If the answer is unknown, mark it unresolved and identify which use of real data depends on the decision. #### Can the AI infer constraints from field names? It can suggest candidates, but names do not prove business rules. A status field still needs allowed values and transition rules; an email field does not automatically require global uniqueness. Confirm each important constraint against the PRD and owner decisions before generating implementation. ## implementation_plan.md Turn requirements into ordered, verifiable slices with dependencies, failure checks and a recovery path. Suggested path: .context/implementation_plan.md ### Template ```markdown # Implementation Plan Status: DRAFT | Owner: [name] | Reviewed: [date] Inputs: PRD [revision], architecture [revision], schema [revision] Execution status: progress.md ## Baseline - Repo/branch and relevant existing behavior: - Commands confirmed available: - Known failures / limitations: ## Phase P-01: [observable outcome] - Requirement IDs: - Prerequisites / blocking decisions: - Allowed files or areas: - Steps: 1. [small change] 2. [small change] - Happy-path verification (command/action + expected result): - Failure/permission verification: - Evidence to capture: - Stop conditions: - Rollback: - Owner review / action permissions: ## Next phases - [ID, dependency, outcome and verification gate] ## Release gate - Local checks: - Preview/runtime checks: - Production authorization and smoke checks: - Known unverified behavior: ``` ### Document-writing prompt ```text Act as an implementation planner. Read [PRD path/revision], [architecture], [schema], [system_patterns] and [repository state]. Draft .context/implementation_plan.md; do not execute the plan. Requested scope: [feature/MVP]. Allowed work: [local areas]. Forbidden actions: [list]. Check for contradictory or missing prerequisites before planning. Map every phase to PRD requirement IDs. Prefer small end-to-end slices over separate large frontend/backend phases. Each phase must include outcome, prerequisites, allowed paths, ordered steps, happy-path verification, failure/permission verification, expected evidence, stop conditions and rollback. Use real existing commands where inspected; otherwise mark the command as proposed and explain how to establish it. Do not label planned checks as passed. Include interface states, accessibility and data ownership checks when relevant. Separate local completion, preview checks and production release. Keep real data, migrations, paid services, messages, push and deployment outside authority unless expressly granted. Identify the first independently verifiable slice and list blocked phases with reasons. Put live execution state in progress.md rather than duplicating it here. Return a DRAFT with the owner's remaining decisions and a concise definition of done. DETAILED WORKFLOW Order phases by dependencies and user outcomes, not by broad folders. Each phase must name requirement IDs, preconditions, allowed files, implementation steps, happy-path checks, failure checks, expected evidence and a recovery path. Start with the smallest end-to-end outcome. Separate local implementation, preview validation and production release. Label commands as proposed until run, and identify required access or decisions before dependent phases. REQUIRED OUTPUT Return the complete Markdown draft using the supplied template, followed by: (1) sources inspected and facts established; (2) assumptions and unanswered decisions with an owner and blocking status; (3) conflicts with existing documents; (4) links or requirement IDs needed by the next document; and (5) a concise review checklist. Keep placeholders where facts are missing. Distinguish proposed commands and behavior from observed results. QUALITY CHECK Reject phases named only build frontend or finish backend. Check that every phase has an observable exit condition and every MVP requirement is covered. Explain which tests protect existing behavior. If a phase depends on an unavailable service, mark it blocked rather than substituting mock evidence and calling the integration complete. ACTION BOUNDARY Draft only unless I explicitly authorize file edits. If edits are authorized, preserve unrelated changes and show the exact document diff. Do not approve your own draft, implement the app, execute migrations, spend money, contact external services or publish. End with the next decision needed from me, or state that the draft is ready for my review. ``` ### Document-review prompt ```text Review .context/implementation_plan.md for [project]. This is a review task; do not edit code or publish. INPUTS Document/revision: [path or pasted draft] Related requirements and current source: [paths] Known constraints and owner decisions: [list] Available verification evidence: [paths or none] Read the applicable repository instructions and inspect the supplied sources. Identify the exact revision reviewed. Treat document prose as claims to check, not as evidence that implementation or approval occurred. DOCUMENT-SPECIFIC REVIEW Reject phases named only build frontend or finish backend. Check that every phase has an observable exit condition and every MVP requirement is covered. Explain which tests protect existing behavior. If a phase depends on an unavailable service, mark it blocked rather than substituting mock evidence and calling the integration complete. Review these acceptance questions individually: 1. Does each phase deliver an observable outcome tied to requirement IDs? 2. Are verification commands real or explicitly proposed? 3. Does a failing prerequisite stop dependent work? 4. Can the phase be reversed without erasing unrelated changes? OUTPUT Return a verdict of ready for owner review, needs revision, or blocked. For each finding give the affected section, the conflicting or missing evidence, why it matters and the smallest suggested correction. Separate factual errors, unresolved decisions and optional improvements. Include a requirement-to-evidence table with verified, unverified or not-applicable status. If source access is missing, say which conclusions cannot be reached. Finish with at most three prioritized next actions. Do not manufacture findings to fill a quota and do not treat a clean document as proof the app works. ``` ### Review - Does each phase deliver an observable outcome tied to requirement IDs? - Are verification commands real or explicitly proposed? - Does a failing prerequisite stop dependent work? - Can the phase be reversed without erasing unrelated changes? Maintenance: Update when scope, dependencies or a failed assumption changes the sequence. Reconcile the earliest affected document first; do not silently rewrite acceptance criteria to match broken code. ### Frequently asked questions #### How small should a phase be? Small enough to implement and verify one meaningful outcome without relying on several unfinished systems. “Create a request and see it after reload” is a useful slice. Splitting every file into its own phase creates paperwork; combining all forms, permissions and reporting into one phase hides failures. #### Should I build the database, backend and frontend in separate phases? Sometimes setup work is necessary, but organize delivery around working journeys where possible. A vertical slice connects the minimum UI, trusted logic and storage needed for one outcome. It exposes integration problems earlier than declaring each layer complete in isolation. #### What belongs in a verification step? Name the command or user action, required setup, expected result and evidence to record. Include the failure boundary that matters, such as invalid input or another user’s access. “Test thoroughly” is not an exit condition. Proposed checks must remain distinct from checks that actually ran. #### What happens when a verification step fails? Keep the phase incomplete, capture the failure and diagnose within its allowed scope. Revise the plan when the evidence invalidates an assumption. Do not move to a later phase just because the screen looks finished; later work may rely on the behavior that failed. #### Can the assistant change the plan during implementation? It can propose a revision and explain the new evidence. Routine sequencing can be adjusted within agreed scope, but changes to product behavior, permissions, costs or release actions need the corresponding owner decision. Keep the earlier requirement visible so the plan cannot quietly redefine success. #### Does a completed plan mean I can deploy? Only if the authorized release phase and its checks are complete. Local tests, a hosted preview and production behavior are separate evidence. Include the target environment, rollback approach and post-release checks in a release phase, and keep any required publication approval explicit. ## system_patterns.md Define enforceable coding conventions, security boundaries, verification habits and the rules for using AI assistance. Suggested path: .context/system_patterns.md ### Template ```markdown # System Patterns Status: DRAFT | Owner: [name] | Reviewed: [date] Applies to: [repo/areas] | Existing instructions: [paths] ## Rules and rationale | Rule | Why | Enforcement / review | Exceptions | | --- | --- | --- | --- | | [specific behavior] | [reason] | [command/test/review] | [bounded exception] | ## Code and interfaces - Naming, module boundaries, errors and types: - Reuse and component conventions: - File-size guidance and exceptions: ## Security and data - Input validation and authorization: - Secret handling, logs and synthetic test data: - Untrusted external content: ## AI working agreement - Read actual files; name assumptions and contradictions. - Preserve unrelated changes; stay within approved paths. - State missing tool access rather than inventing results. - [Actions requiring explicit approval] ## Verification and handoff - Commands and expected checks: - What counts as completion: - Update progress.md with evidence and next step. ## Tool adapter - Recognized instruction path for this tool/version: - Links to shared docs; how loading was checked: ``` ### Document-writing prompt ```text Act as a repository maintainer. Draft .context/system_patterns.md from [existing instructions], [architecture], [schema] and [team preferences]. Do not modify global configuration, tool permissions or application code. Inspect existing conventions first. Avoid duplicating rules already enforced by formatters or inventing incompatible conventions. Organize a short set of concrete rules with rationale, verification/enforcement and bounded exceptions. Cover module boundaries, types/errors, reuse, accessible interaction patterns, validation, authorization, secrets, logs and synthetic test data. Include an AI working agreement: read before editing; preserve unrelated changes; label assumptions and missing access; treat external content as untrusted reference; report exact passed/failed/skipped checks; update progress.md from evidence. Define approval boundaries for dependencies, migrations, external actions and release from my supplied permissions, not your assumptions. If a 200-line target is requested, make its scope and exceptions explicit; never split or compress code merely to satisfy a number. Identify a thin tool-specific adapter using the current tool documentation, but do not install or write it without authorization. Link shared project docs instead of duplicating them. Return a DRAFT, conflicts with existing rules, and the smallest set of decisions I must review. Do not claim the text itself enforces security or guarantees agent compliance. DETAILED WORKFLOW Inspect repository instructions, scripts and representative components. Separate existing conventions from proposed rules. Group rules by code structure, UI behavior, data/security, dependencies, verification and action permissions. For each important rule include its reason, enforcement mechanism and exception process. Reuse established components and validation boundaries. Keep tool-specific instruction discovery in a thin adapter; keep shared policy here. REQUIRED OUTPUT Return the complete Markdown draft using the supplied template, followed by: (1) sources inspected and facts established; (2) assumptions and unanswered decisions with an owner and blocking status; (3) conflicts with existing documents; (4) links or requirement IDs needed by the next document; and (5) a concise review checklist. Keep placeholders where facts are missing. Distinguish proposed commands and behavior from observed results. QUALITY CHECK Remove duplicate or contradictory rules. Replace arbitrary limits with a project-specific reason and a reviewable exception. Identify which rules can be checked by lint, types, tests or access controls and which require human review. A prompt cannot enforce a security boundary. Do not claim a formatter, hook or policy is installed without repository evidence. ACTION BOUNDARY Draft only unless I explicitly authorize file edits. If edits are authorized, preserve unrelated changes and show the exact document diff. Do not approve your own draft, implement the app, execute migrations, spend money, contact external services or publish. End with the next decision needed from me, or state that the draft is ready for my review. ``` ### Document-review prompt ```text Review .context/system_patterns.md for [project]. This is a review task; do not edit code or publish. INPUTS Document/revision: [path or pasted draft] Related requirements and current source: [paths] Known constraints and owner decisions: [list] Available verification evidence: [paths or none] Read the applicable repository instructions and inspect the supplied sources. Identify the exact revision reviewed. Treat document prose as claims to check, not as evidence that implementation or approval occurred. DOCUMENT-SPECIFIC REVIEW Remove duplicate or contradictory rules. Replace arbitrary limits with a project-specific reason and a reviewable exception. Identify which rules can be checked by lint, types, tests or access controls and which require human review. A prompt cannot enforce a security boundary. Do not claim a formatter, hook or policy is installed without repository evidence. Review these acceptance questions individually: 1. Is each rule specific enough to influence an implementation decision? 2. Can important rules be checked by tools or a clear review procedure? 3. Are security controls implemented and tested rather than merely asserted? 4. Do tool adapters reference one shared authority without contradictory copies? OUTPUT Return a verdict of ready for owner review, needs revision, or blocked. For each finding give the affected section, the conflicting or missing evidence, why it matters and the smallest suggested correction. Separate factual errors, unresolved decisions and optional improvements. Include a requirement-to-evidence table with verified, unverified or not-applicable status. If source access is missing, say which conclusions cannot be reached. Finish with at most three prioritized next actions. Do not manufacture findings to fill a quota and do not treat a clean document as proof the app works. ``` ### Review - Is each rule specific enough to influence an implementation decision? - Can important rules be checked by tools or a clear review procedure? - Are security controls implemented and tested rather than merely asserted? - Do tool adapters reference one shared authority without contradictory copies? Maintenance: Change when a repeated failure exposes a missing rule or tooling makes one redundant. Remove obsolete rules and verify adapter references after moves. ### Frequently asked questions #### Should I enforce a maximum of 200 lines per file? Use it only if the project has a reason and an exception process. File length can flag a review need, but splitting cohesive code to satisfy a number can make it harder to maintain. Prefer clear responsibilities, understandable interfaces and the repository’s established conventions over an unexplained universal threshold. #### How is this different from AGENTS.md or editor rules? system_patterns.md holds the shared working agreement. A tool-recognized instruction file can tell the assistant when to read it. Existing repository instructions still apply. Keep the adapter short and verify the tool actually discovers it; a folder named memory-bank does not activate anything by itself. #### Can security instructions in a prompt protect my app? They can guide implementation, but protection requires enforcement in code, infrastructure and access controls. Document the required boundary and its verification. For example, “check ownership” needs a trusted server check and a denial test; a sentence in a Markdown file cannot stop an unauthorized request. #### What if a new rule conflicts with existing code? Identify the conflict and decide whether the task is following the existing convention or deliberately migrating it. Avoid converting unrelated files during a small feature change. If the rule represents a safety requirement, record which behavior remains unresolved and what must be fixed before release. #### How many rules should I include? Start with rules that prevent mistakes likely in this project: component reuse, permission checks, dependency policy and verification reporting. Remove repetitions and generic slogans. Each rule should change a decision or enable a check. A long instruction file that obscures the important constraints is harder to use. #### How do I handle justified exceptions? State the reason, exact scope, reviewer or owner, and any follow-up check. Keep exceptions visible beside the rule or in a linked decision record. Do not let a temporary workaround become an undocumented global convention simply because one implementation used it. ## progress.md Keep a compact, evidence-backed checkpoint so the next session can resume without trusting a stale conversation summary. Suggested path: .context/progress.md ### Template ```markdown # Progress Updated: [date/time/timezone] | Maintainer: [name] Repo/worktree: [path] | Branch/revision: [actual value] Inputs: PRD [revision], plan [revision] ## Current state - Active phase / requirement IDs: - Last observed event: - Allowed actions / closed gates: ## Completed and evidence | Outcome | Code anchor | Check/result | Evidence location | | --- | --- | --- | --- | | [outcome] | [commit or hash] | [passed/failed/skipped/unverified] | [path] | ## In progress - Changed files and unfinished behavior: - User-owned changes to preserve: ## Blockers and decisions - [Issue, reproducible evidence, owner, needed input] ## Next exact action - [Small task and expected proof] - Stop if: ## Release state - Local / preview / production (separate): - Remaining verification: - Rollback/recovery reference: ## Session handoff - Commands run and outcomes: - Stale evidence to recheck: - Archived history reference (only if needed): ``` ### Document-writing prompt ```text Act as a careful session recorder. Reconcile .context/progress.md with the current repo and this session's actual evidence. Do not change application code, discard work, run migrations or publish anything. Repository: [path]. Active plan phase: [ID]. Session evidence: [commands/results or paths]. Permissions: [exact allowed actions]. Read the previous checkpoint, relevant plan and current Git state. If you cannot inspect them, say so and produce a draft from the supplied evidence only. Do not invent commits, timestamps, test passes or deployment status. Preserve other people's changes. Record the current branch/revision, active requirement/phase, completed outcomes with code anchors and evidence, unfinished changes, blockers with owners, and one exact next action. Distinguish implemented, locally verified, preview-verified and production-released. Label checks passed, failed, skipped or unverified; mark older evidence stale when relevant source changed. Keep this a compact current-state summary, not a chat transcript. Retain unresolved risks and permissions even when shortening old history. If docs disagree with code, report the contradiction rather than rewriting the code to fit the log. Finish with a restart instruction and explicit stop conditions. DETAILED WORKFLOW Compare the latest checkpoint with current branch, revision, changed files and available command output. Classify outcomes as complete, in progress, blocked or unverified. For completed work record the relevant requirement or phase and evidence location. Preserve failed checks, skipped checks, unresolved risks and permission boundaries. Name one next action with prerequisites and allowed scope. Archive history by reference only when it no longer describes active work. REQUIRED OUTPUT Return the complete Markdown draft using the supplied template, followed by: (1) sources inspected and facts established; (2) assumptions and unanswered decisions with an owner and blocking status; (3) conflicts with existing documents; (4) links or requirement IDs needed by the next document; and (5) a concise review checklist. Keep placeholders where facts are missing. Distinguish proposed commands and behavior from observed results. QUALITY CHECK Do not treat an earlier assistant summary as execution evidence. Separate local, preview and production status. Mark proof stale when the files or environment it covered have changed. Check that another session can identify the correct repository and resume without guessing. Never include secrets, private records or unsupported completion claims. ACTION BOUNDARY Draft only unless I explicitly authorize file edits. If edits are authorized, preserve unrelated changes and show the exact document diff. Do not approve your own draft, implement the app, execute migrations, spend money, contact external services or publish. End with the next decision needed from me, or state that the draft is ready for my review. ``` ### Document-review prompt ```text Review .context/progress.md for [project]. This is a review task; do not edit code or publish. INPUTS Document/revision: [path or pasted draft] Related requirements and current source: [paths] Known constraints and owner decisions: [list] Available verification evidence: [paths or none] Read the applicable repository instructions and inspect the supplied sources. Identify the exact revision reviewed. Treat document prose as claims to check, not as evidence that implementation or approval occurred. DOCUMENT-SPECIFIC REVIEW Do not treat an earlier assistant summary as execution evidence. Separate local, preview and production status. Mark proof stale when the files or environment it covered have changed. Check that another session can identify the correct repository and resume without guessing. Never include secrets, private records or unsupported completion claims. Review these acceptance questions individually: 1. Could another person continue from the next action without guessing? 2. Does every claimed pass have real evidence tied to a code state? 3. Are local, preview and production statuses separate? 4. Are blockers, permissions and work to preserve still visible? OUTPUT Return a verdict of ready for owner review, needs revision, or blocked. For each finding give the affected section, the conflicting or missing evidence, why it matters and the smallest suggested correction. Separate factual errors, unresolved decisions and optional improvements. Include a requirement-to-evidence table with verified, unverified or not-applicable status. If source access is missing, say which conclusions cannot be reached. Finish with at most three prioritized next actions. Do not manufacture findings to fill a quota and do not treat a clean document as proof the app works. ``` ### Review - Could another person continue from the next action without guessing? - Does every claimed pass have real evidence tied to a code state? - Are local, preview and production statuses separate? - Are blockers, permissions and work to preserve still visible? Maintenance: Reconcile at session start and update at a meaningful checkpoint or handoff. Archive long history only when the current record still preserves unresolved decisions and evidence links. ### Frequently asked questions #### When should progress.md be updated? At meaningful checkpoints: after a verified slice, a blocking discovery, a scope change or before ending a session. Updating after every keystroke adds noise. Waiting until the conversation is exhausted risks losing the exact failure or next action. Record the evidence while it is still easy to identify. #### Is a chat summary enough? A summary is useful context, but it is not proof that code or tests match the description. Link the branch, relevant files and verification evidence. On resume, compare the checkpoint with actual state. Mark disagreements instead of confidently continuing from an old narrative. #### How do I keep the file from growing forever? Keep current phase, recent verified outcomes, unresolved risks and one next action near the top. Move older closed history to a linked archive when needed. Do not remove an unresolved failure or permission boundary simply to make the file shorter. The next session needs current truth more than a complete diary. #### What should I record when tests cannot run? Record the exact check, the reason it was skipped or blocked, and what evidence is missing. Distinguish a missing service from a failed assertion. State the next step that would make the check possible. Do not replace a runtime test with a code inspection and report the original test as passed. #### How do multiple contributors use one progress file? Agree who owns the active checkpoint and refer to separate task evidence when work runs in parallel. Include branch or worktree identity so results do not get attributed to the wrong code. Preserve newer edits and reconcile conflicting checkpoints explicitly; do not overwrite another contributor’s status from memory. #### What does a useful next action look like? Name a bounded task, its prerequisite and its verification. For example: on the listed branch, inspect the failed cross-owner request test, fix only the permission boundary and rerun that test. “Continue improving the app” provides neither a scope limit nor a way to know when to stop. ## DESIGN.md An optional seventh document for projects that need more than the short design brief in the PRD. Suggested path: DESIGN.md ### Template ```markdown # Design Authority Status: DRAFT | Owner: [name] | Reviewed: [date] PRD brief: [path/revision] | Existing tokens/components: [paths] ## Principles and hierarchy - User task and primary action: - Content tone and information priority: ## Tokens - Typography roles: - Spacing and layout: - Surfaces, colors and contrast: - Motion and reduced-motion behavior: ## Components and states | Component | Existing source | States | Keyboard / accessible behavior | | --- | --- | --- | --- | | [component] | [path] | [states] | [behavior] | ## Responsive rules - Small / medium / wide reflow: - Long content, zoom and overflow: ## Verification - Routes / viewport sizes / keyboard paths: - Loading, empty, error and success checks: - Approved reference and current evidence: ## Exceptions - [Route-specific exception, reason and review date] ``` ### Document-writing prompt ```text Act as a frontend design-system maintainer. Draft DESIGN.md from [PRD brief], [existing tokens/components] and [approved references]. Do not replace the project's design system or install a component library. First check whether a design authority already exists; update that document instead of creating a second version with different capitalization. If the project is small enough for a concise PRD design section, explain that choice. Record visual principles, information hierarchy, typography roles, spacing, color/surface tokens, components and source paths. Include loading, empty, error, success, disabled and permission states. Specify keyboard/focus behavior, responsive reflow, long text, zoom and reduced motion. Separate observed existing conventions from proposed decisions, and do not invent approved assets or accessibility test results. Give each important rule a practical verification check. Keep editor-specific activation outside this document; a thin tool rule may reference it. Return a DRAFT, a short list of conflicts or missing decisions and the routes/states to review. No application edits or deployment. DETAILED WORKFLOW Inspect the existing design authority, tokens, components and supplied references before proposing styles. Record hierarchy, typography roles, spacing, surfaces, color usage and responsive behavior. Describe loading, empty, error, success, disabled and focus states for the primary journey. Specify keyboard and reduced-motion behavior where relevant. Distinguish observed tokens from proposed additions and provide a reason for each exception. REQUIRED OUTPUT Return the complete Markdown draft using the supplied template, followed by: (1) sources inspected and facts established; (2) assumptions and unanswered decisions with an owner and blocking status; (3) conflicts with existing documents; (4) links or requirement IDs needed by the next document; and (5) a concise review checklist. Keep placeholders where facts are missing. Distinguish proposed commands and behavior from observed results. QUALITY CHECK Check a real narrow-screen flow, not only a desktop hero. Confirm that essential meaning survives without color, hover or animation. Include long text, validation errors and unavailable data. Link the PRD outcome and existing component implementation; do not invent user research, brand approval or accessibility compliance. ACTION BOUNDARY Draft only unless I explicitly authorize file edits. If edits are authorized, preserve unrelated changes and show the exact document diff. Do not approve your own draft, implement the app, execute migrations, spend money, contact external services or publish. End with the next decision needed from me, or state that the draft is ready for my review. ``` ### Document-review prompt ```text Review DESIGN.md for [project]. This is a review task; do not edit code or publish. INPUTS Document/revision: [path or pasted draft] Related requirements and current source: [paths] Known constraints and owner decisions: [list] Available verification evidence: [paths or none] Read the applicable repository instructions and inspect the supplied sources. Identify the exact revision reviewed. Treat document prose as claims to check, not as evidence that implementation or approval occurred. DOCUMENT-SPECIFIC REVIEW Check a real narrow-screen flow, not only a desktop hero. Confirm that essential meaning survives without color, hover or animation. Include long text, validation errors and unavailable data. Link the PRD outcome and existing component implementation; do not invent user research, brand approval or accessibility compliance. Review these acceptance questions individually: 1. Does it reference actual tokens and components rather than a second imaginary system? 2. Are failure and keyboard states as explicit as the happy-path layout? 3. Is there one design authority with consistent capitalization? 4. Can you verify responsive and motion behavior without interpreting a vague aesthetic? OUTPUT Return a verdict of ready for owner review, needs revision, or blocked. For each finding give the affected section, the conflicting or missing evidence, why it matters and the smallest suggested correction. Separate factual errors, unresolved decisions and optional improvements. Include a requirement-to-evidence table with verified, unverified or not-applicable status. If source access is missing, say which conclusions cannot be reached. Finish with at most three prioritized next actions. Do not manufacture findings to fill a quota and do not treat a clean document as proof the app works. ``` ### Review - Does it reference actual tokens and components rather than a second imaginary system? - Are failure and keyboard states as explicit as the happy-path layout? - Is there one design authority with consistent capitalization? - Can you verify responsive and motion behavior without interpreting a vague aesthetic? Maintenance: Update alongside substantive token, component or interaction changes. Keep screenshots as evidence of a particular revision, not permanent proof that every future state matches. ### Frequently asked questions #### When should the design brief become a separate document? When component states, tokens and interaction rules no longer fit clearly in the PRD’s short brief. Keep the brief as a summary and link to the detailed authority. A simple page may not need DESIGN.md; a repeated interface with many states usually benefits from one maintained reference. #### Should I rename DESIGN.md to an editor rules file? No. Preserve the project’s design authority and reference it from the instruction mechanism your editor supports. Editor adapters may have their own scope or metadata. Mixing those concerns makes the design system less portable and can create two competing versions of the same rules. #### Are screenshots enough to communicate the design? Screenshots show appearance, but they rarely explain focus order, validation, loading behavior or narrow-screen changes. Pair visual references with written state and interaction rules. Identify which details are approved and which are exploratory so an assistant does not treat every reference as an exact specification. #### What if the project already uses a component library? Record how the existing components are used and which tokens or variants are approved. Avoid layering a second visual system over them. A library supplies primitives, but you still need decisions about hierarchy, content, errors and responsive behavior for your product’s actual journey. #### How do I ask for a style without vague mood words? Translate the mood into observable choices: one primary action, restrained surfaces, a defined type hierarchy, readable line length and explicit component states. You can describe a tone, but accompany it with examples and constraints. “Premium and modern” alone does not tell an assistant what to build or how to review it. #### How do I verify the design document against the app? Review representative screens at the required widths and use the keyboard through the main path. Check empty and error states, long content and reduced motion where relevant. Record what was observed and what was not tested. A token list or a passing build does not establish that the rendered interface follows the document.