Build a Safe, Verifiable App Prototype with Codex

Turn the supplied app concept into the smallest useful, testable prototype. Use Codex to inspect available project materials, plan a coherent vertical slice, make only authorized local changes, and report verification without overstating what occurred.

## Project inputs

App idea: [App idea]
Target users and core problem: [Target users and core problem]
Definition of done: [Definition of done]
Must-have features: [Must-have features]
Constraints and prohibited features: [Constraints and prohibited features]
Repository or starter files: [Repository or starter files]
Preferred stack: [Preferred stack]
Environment and run commands: [Environment and run commands]
Data and integrations: [Data and integrations]
UI and accessibility direction: [UI and accessibility direction]
Verification commands: [Verification commands]
Working mode and permitted actions: [Working mode and permitted actions]

## Input and access rules

The minimum inputs for scope planning are the app idea, target users and problem, must-have features, constraints, and definition of done. Editing also requires an accessible workspace or supplied files, enough environment information to avoid unsafe guesses, and explicit permission for the intended actions.

Treat stack preferences, design direction, suggested data entities, integrations, and verification commands as useful context rather than confirmed repository facts until inspection supports them.

If a blocking prerequisite is missing or contradictory, ask focused questions before editing. A blocking issue includes an unclear primary user flow, incompatible acceptance criteria, unavailable required files, uncertain authority, unknown handling of sensitive data, or a requested integration without a safe test method. When planning can continue safely, state a bounded assumption and keep the affected item marked unverified. Never invent files, dependencies, credentials, command results, or stakeholder decisions.

## Codex operating boundaries

Use Codex's workspace inspection, file-editing, and shell capabilities only when those capabilities are available in the current session and permitted by the working mode. Cite repository observations using file paths and relevant symbols or line ranges when practical.

If Codex cannot access a referenced file, execute a command, or edit the workspace, provide a proposed patch or command instead and label it NOT EXECUTED. Do not imply that a proposal changed the repository.

Unless expressly authorized, do not:

- access or modify production systems or production data;
- deploy, publish, push, merge, open a pull request, or create a release;
- commit changes or alter remote resources;
- run destructive database, filesystem, reset, cleanup, or migration commands;
- install or upgrade dependencies, change lockfiles, or make external network calls;
- add authentication, payments, analytics, tracking, background jobs, or third-party services;
- read, print, copy, or embed secrets, tokens, private keys, credentials, or unredacted personal data.

Pause for explicit approval before any dependency installation, lockfile change, schema migration with data-loss risk, external API call, destructive command, or action beyond the stated permissions. Prefer local or test fixtures, reversible changes, backups where relevant, and narrowly scoped patches. Stop if an unexpected secret, production connection, destructive script, or unrelated repository change is discovered.

## Evidence discipline

Maintain an evidence ledger throughout the work. Classify material statements as one of:

- SUPPLIED FACT: stated in the project inputs;
- OBSERVATION: directly supported by an inspected file, configuration, interface, or repository structure;
- EXECUTION EVIDENCE: supported by a command that actually ran, including command, exit status, and material output;
- ASSUMPTION: a reversible working choice made because evidence is incomplete;
- UNKNOWN: information that remains unavailable;
- CONFLICT: incompatible inputs or evidence requiring resolution.

Do not convert an assumption into a fact. Reconcile conflicts when repository evidence clearly resolves them; otherwise preserve the conflict and explain its effect on scope or verification.

## Prototype workflow

### 1. Establish the vertical slice

Restate the target user, triggering situation, primary action, persisted or returned result, and user-visible success condition. Define one end-to-end vertical slice that satisfies the definition of done with the fewest moving parts.

Separate requested capabilities into:

- prototype-critical;
- deferred but compatible;
- explicitly excluded.

Challenge features that require authentication, payments, external services, asynchronous jobs, multi-role permissions, complex administration, or premature abstraction unless they are essential and authorized. Record the trade-off when simplicity reduces extensibility, fidelity, scale, or production readiness.

### 2. Inspect the implementation context

If files are available, inspect the repository before proposing architecture. Identify the application entry points, framework and version, package manifests and lockfiles, build scripts, routing conventions, persistence layer, schema or migrations, existing UI system, test framework, linting or type-checking configuration, environment templates, and current working-tree state when accessible.

Distinguish existing conventions from preferred-stack requests. Preserve working behavior and avoid unrelated formatting or refactoring. If the repository is empty, propose the minimum scaffold; do not create it unless authorized.

Report important failure risks such as incompatible runtime versions, missing scripts, uncommitted user changes, absent test infrastructure, unsafe defaults, unclear database ownership, undocumented API dependencies, or conflicting framework conventions.

### 3. Specify the prototype before editing

Define these task-specific artifacts:

- user flow covering entry, primary action, success, validation error, system error, empty state, and recovery;
- minimal entities, fields, identifiers, defaults, relationships, lifecycle rules, and representative non-sensitive records;
- routes or API operations, including method, path, request shape, validation boundary, success response, error response, and relevant status codes;
- UI pages or components, their loading and disabled states, keyboard behavior, labels, focus handling, responsive behavior, and user-facing error messages;
- validation and error matrix covering malformed input, missing records, duplicates where relevant, persistence failure, unavailable integrations, and unsupported operations;
- file change map listing each file to create or modify, its purpose, dependencies, and rollback method;
- acceptance cases traceable to the definition of done.

Do not design entities, endpoints, or components that the chosen vertical slice does not need.

### 4. Select an implementation checkpoint

Before changing files, state whether the current mode permits implementation. Present the proposed file set, notable architectural decisions, commands expected to run, approval-sensitive actions, and rollback approach.

If implementation is not authorized or a blocking question remains, stop at a plan and patch proposal. If implementation is authorized, proceed in small checkpoints that keep the project recoverable.

### 5. Implement incrementally

For each checkpoint:

1. State the behavior being added and the acceptance case it addresses.
2. Inspect the relevant existing code before editing.
3. Make the smallest coherent change using repository conventions.
4. Add or update focused tests where the repository supports them.
5. Run the narrowest safe verification available before continuing.
6. Record files changed, command evidence, failures, and unresolved effects.

A typical sequence is persistence or in-memory state, domain behavior, route or handler, UI flow, validation and error handling, then end-to-end integration. Adapt this sequence to the actual stack rather than forcing layers that do not exist.

Use server-side validation at trust boundaries even when client-side validation is present. Avoid leaking stack traces, internal identifiers, secrets, or sensitive data in responses and logs. Use semantic controls, associated labels, visible focus, keyboard-operable interactions, meaningful status messages, and reasonable narrow-screen layouts where the UI requires them.

When a verification step fails, diagnose from available evidence. Fix only failures caused by the authorized change. Do not conceal pre-existing failures or broaden scope without approval. If recovery is uncertain, stop and provide the safest rollback instructions.

### 6. Verify against acceptance criteria

Use supplied commands when safe and applicable, then supplement them with commands supported by inspected project configuration. Verification may include targeted tests, broader regression tests, type checks, linting, builds, API request checks, data persistence checks, and manual UI scenarios.

For every check, report:

- acceptance case or risk addressed;
- exact command or manual procedure;
- expected observation;
- actual observation and exit status, if executed;
- evidence source;
- state: PASS, FAIL, BLOCKED, or NOT RUN.

A command proposal is not execution evidence. A successful build is not proof that the user flow works. A passing unit test is not proof of deployment. Reconcile every definition-of-done item with evidence or leave it explicitly unresolved.

## Required deliverable

Return the following sections:

### Prototype Decision Record
Include the user, problem, vertical slice, definition-of-done interpretation, scope exclusions, key trade-offs, and implementation mode.

### Evidence and Unknowns Ledger
Provide each material fact, observation, assumption, unknown, or conflict with its source and effect on the work.

### Repository Findings
List inspected files and detected framework, runtime, scripts, architecture conventions, test setup, working-tree considerations, and relevant risks. Mark inaccessible or uninspected areas.

### User Flow and State Coverage
Describe the entry, primary action, success, empty, loading, validation-error, system-error, and recovery states.

### Data and Interface Contract
Document only the entities and fields required for the slice, plus routes or API operations, validation rules, response behavior, status codes, and failure handling.

### File Change and Rollback Map
For each file, state CREATE, MODIFY, or PROPOSED; explain its purpose, dependencies, risk, and rollback method.

### Incremental Change Log
For every checkpoint, show the behavior addressed, concise patch or actual edit summary, files affected, and checkpoint verification. Do not reproduce unchanged files unnecessarily.

### Acceptance Evidence Matrix
Map every acceptance criterion to its test or manual procedure, expected result, actual result, evidence reference, and PASS, FAIL, BLOCKED, or NOT RUN state.

### Final Handoff
Separate:

- changes actually made;
- changes only proposed;
- checks actually executed;
- checks not run or blocked;
- known limitations and deferred features;
- approval-sensitive next actions;
- exact local run and rollback instructions.

Use FIXED, IMPLEMENTED, TESTED, or VERIFIED only when the corresponding action occurred and supporting evidence is reported. Use DEPLOYED, PUBLISHED, APPROVED, MERGED, or RELEASED only when that action was explicitly authorized, actually performed, and evidenced. Otherwise use proposed, locally changed, unverified, blocked, or not run.

Begin by validating the minimum inputs and permissions. Ask only blocking questions; otherwise establish the vertical slice and continue within the authorized mode.