You are responsible for taking this project from initial review to a complete, tested, reproducible, open-source-ready, and deployable implementation with minimal involvement from me.
The primary project requirements are in:
[PRIMARY_REQUIREMENTS_FILE]
Supporting domain knowledge is available in:
[DOMAIN_REFERENCE_FILE_1][DOMAIN_REFERENCE_FILE_2][ADDITIONAL_REFERENCE_FILES_IF_ANY]
Treat the provided materials as the authoritative source for domain knowledge. Do not perform external domain research unless the supplied material is genuinely insufficient or the requirements explicitly demand current external information.
Some reference files may be very large. Do not load or read large files in full without a clear reason. Navigate them intelligently:
- Inspect their structure and headings.
- Read top-down at the section level.
- Open only the portions relevant to the task currently being implemented.
- Return to other sections only when required.
Avoid wasting context on information that is not immediately useful.
Begin by reviewing the primary requirements and the relevant supporting material.
Then produce a brief implementation overview covering:
- your understanding of the deliverable;
- the proposed architecture;
- the main milestones;
- important technical or product decisions;
- risks, ambiguities, or constraints you identified.
Ask questions only when an answer is truly required and cannot be safely inferred from the requirements, established conventions, or reasonable engineering judgment.
Do not ask me to choose between ordinary implementation details that you are capable of deciding yourself.
If a decision is reversible, low-risk, or primarily aesthetic, make the decision and proceed.
If additional tooling, credentials, authentication, permissions, or one-time setup would materially improve your autonomy, tell me early. My intervention should be treated as a process failure unless it is genuinely unavoidable, but do not hesitate to ask when no safe alternative exists.
Perform all work in an isolated, project-local environment that does not interfere with the rest of the machine.
Use the ecosystem-recommended isolation mechanism, such as:
- a virtual environment;
- a project-local package environment;
- containers;
- isolated runtime tooling;
- another framework-standard approach.
Start from a clean project state.
Use current stable versions of frameworks, libraries, runtimes, and tools unless the requirements impose a version constraint or a newer version creates a known compatibility problem.
The project must remain reproducible on another developer's machine throughout development, not only at the end.
Initialize a Git repository before beginning implementation.
Use the GitHub CLI to obtain my configured identity where possible, including:
- name;
- email;
- GitHub username.
Configure the repository-local Git identity so it does not need to be supplied repeatedly.
Do not modify global Git configuration unless explicitly necessary.
Commit incrementally at meaningful milestones. Commits should represent coherent, working units of progress.
Use clear, one-line commit messages describing the work completed.
Do not use semantic prefixes such as:
feat:fix:chore:refactor:
Do not add co-authors, generated-by messages, assistant attribution, or unrelated metadata to commits.
Before every commit:
- update the README;
- update or add relevant automated tests;
- run the applicable validation commands;
- review the persistent project-guidance file;
- verify that the commit forms a meaningful and stable checkpoint.
Create a project-local Markdown file containing the durable working rules, architectural constraints, quality expectations, and project-specific decisions that should remain relevant throughout implementation.
Use a suitable name such as:
PROJECT_GUIDELINES.mdENGINEERING_RULES.mdPROJECT_CONTEXT.md
This file is for your own continuity and self-review.
After every milestone, consult it and check that the implementation still follows the agreed direction.
Update it whenever a new durable decision, constraint, convention, or lesson becomes relevant.
All Markdown files other than the root README.md must be excluded from Git using a wildcard-based .gitignore rule rather than hardcoded filenames, unless a project requirement explicitly requires another Markdown file to be committed.
Keep the root README.md accurate throughout development.
Do not postpone README work until the end.
The README should provide enough information for a new developer to reproduce, run, test, understand, and deploy the project on a clean machine.
Maintain, where relevant:
- project purpose;
- architecture overview;
- prerequisites;
- installation;
- environment setup;
- local development commands;
- frontend and backend commands;
- database setup and migrations;
- testing;
- linting;
- type-checking;
- builds;
- deployment;
- environment variables;
- troubleshooting;
- known constraints;
- any workaround or machine-specific issue encountered.
Any quirk, compatibility fix, setup detail, or non-obvious command needed during development must be documented immediately so another user gets the intended behavior.
Treat divergence between the repository and the README as a defect.
Assume the final deliverable will be a public repository.
Keep the project safe and appropriate for open-source publication:
- no secrets;
- no machine-specific absolute paths;
- no private data;
- no proprietary material unless explicitly supplied for inclusion;
- no unnecessary generated artifacts;
- no credentials in Git history;
- no undocumented local assumptions;
- appropriate license and metadata when required;
- clean repository structure;
- clear setup instructions.
Prefer portable, conventional solutions over environment-specific hacks.
Never commit secrets or real credentials.
Keep .env and equivalent local secret files ignored.
Maintain .env.example whenever environment variables are introduced, changed, or removed.
.env.example must remain synchronized with the actual variable names used by the application and contain safe dummy values or clear placeholders.
Validate required environment variables early and fail with useful errors.
Avoid introducing environment variables when configuration can safely remain static and non-sensitive.
Follow the stated technology stack. Where the requirements leave room for judgment, prefer established, maintainable, framework-native patterns.
Apply SOLID principles and equivalent modular design principles even when the implementation is not object-oriented.
Optimize for:
- strong boundaries;
- separation of concerns;
- testability;
- maintainability;
- composability;
- explicit data flow;
- predictable failure modes;
- ease of future modification.
Avoid unnecessary abstraction, but do not create tightly coupled code that becomes difficult to test or extend.
Choose the simplest architecture that fully supports the expected behavior and likely evolution of the project.
Prioritize early decisions that would be expensive or disruptive to change later, such as:
- repository structure;
- application boundaries;
- data model;
- authentication strategy;
- API contracts;
- deployment model;
- environment configuration;
- testing strategy;
- framework initialization.
Delay low-cost and reversible decisions until they become relevant.
Use strict, meaningful typing throughout the project.
For TypeScript:
- enable strict compiler settings;
- avoid
any; - avoid unsafe type assertions;
- model domain data explicitly;
- validate data at system boundaries;
- use generated types where appropriate;
- ensure compilation catches as many errors as reasonably possible.
For Python or Django backends:
- use modern type hints;
- type public interfaces;
- use typed schemas, serializers, services, and data structures where appropriate;
- run a suitable static type checker when practical;
- avoid relying on implicit or ambiguous shapes.
Do not use typing as decoration. Types should improve correctness and design clarity.
Do not manually create boilerplate files that the framework or an official generator can produce correctly.
Use:
- official project initializers;
- framework CLIs;
- migration generators;
- component generators;
- schema generators;
- code generation tools;
- package-manager-native commands.
Use non-interactive flags wherever available.
Follow the framework's current recommended initialization and project structure rather than inventing a custom setup without a strong reason.
Generated output should still be reviewed, cleaned up, and tested.
When a requirement can be solved reliably by a focused, well-maintained library, prefer the library over custom implementation.
Before adding a dependency, confirm that it is:
- actively maintained;
- compatible with the current stack;
- appropriately licensed;
- reasonably scoped;
- not redundant with existing framework functionality;
- worth its maintenance and supply-chain cost.
Do not add large dependencies for trivial functionality.
Do not reimplement established security-sensitive or standards-heavy functionality.
Use targeted web research when technical verification is needed, but do not get trapped in broad or repetitive research loops. Search only for the specific fact, compatibility issue, API, or recommended pattern needed to proceed.
Do not add comments inside source code.
Code should be understandable through:
- naming;
- structure;
- small focused units;
- explicit types;
- clear interfaces;
- appropriate abstractions;
- tests.
Avoid commented-out code.
Avoid placeholder implementations unless they are explicitly tracked and necessary for an incremental milestone.
Do not leave unresolved TODOs in the final deliverable.
Documentation files, commit messages, and test names may explain behavior where appropriate; the prohibition applies to comments embedded in source code.
When a frontend is part of the project, use the required stack and favor a polished, restrained interface.
Unless the requirements specify otherwise:
- use TypeScript;
- use shadcn/ui where suitable;
- use accessible primitives;
- use a slate, zinc, neutral, or Vercel-inspired visual direction;
- maintain strong contrast and readable hierarchy;
- support responsive layouts;
- include loading, empty, success, and error states;
- use semantic HTML;
- ensure keyboard accessibility;
- avoid excessive animation or visual noise.
Theme and aesthetic decisions are yours unless they materially affect product behavior.
Build the interface in a way that keeps logic independently testable. UI components should remain thin where possible, with behavior extracted into typed functions, hooks, services, schemas, or state modules.
When a backend is part of the project:
- follow framework-native architecture;
- use migrations for schema changes;
- validate all external input;
- return consistent error responses;
- isolate business logic from transport or framework plumbing;
- use explicit service boundaries where useful;
- prevent secrets or internal implementation details from leaking through errors;
- add suitable logging without exposing sensitive data;
- design APIs and data models for testability.
For Django-based work, use modern Django conventions, type hints, appropriate serializers or schemas, and clean separation between views, business logic, and persistence.
Automated tests are part of the implementation, not a final cleanup activity.
Add or update tests alongside every feature.
Both frontend and backend should have automated test coverage appropriate to their responsibilities.
Tests should collectively preserve the functional context of everything implemented so far, allowing future changes to be made confidently.
Prefer testing:
- business rules;
- validation;
- transformations;
- state transitions;
- API contracts;
- error handling;
- permissions;
- integration boundaries;
- regressions;
- critical user flows at the appropriate layer.
Do not over-test framework internals or purely visual details.
Design the application so most meaningful behavior can be tested without a browser.
Use browser automation only for flows that genuinely require browser-level verification.
When Playwright or a similar browser CLI is available, use it autonomously for final interaction review, critical flows, layout sanity checks, and behavior that unit or integration tests cannot adequately validate.
I should not need to manually review routine functionality.
At appropriate milestones, run the relevant checks, such as:
- formatting;
- linting;
- static analysis;
- frontend type-checking;
- backend type-checking;
- unit tests;
- integration tests;
- migration validation;
- production builds;
- dependency checks;
- browser smoke tests;
- startup checks.
Do not knowingly commit a broken build or failing test suite.
When a check cannot be run, document why and provide the exact command expected to run elsewhere.
Use timeouts for commands that may hang, wait indefinitely, start persistent processes, or depend on unreliable external behavior.
Prefer bounded, deterministic commands.
Work in coherent milestones. A typical order is:
- inspect requirements and references;
- establish project guidance;
- initialize the repository and isolated environment;
- scaffold using official tools;
- establish formatting, linting, typing, and test infrastructure;
- define architecture and contracts;
- implement the smallest end-to-end functional path;
- expand feature coverage incrementally;
- validate edge cases and failure states;
- conduct browser-level review where necessary;
- prepare deployment;
- perform final open-source and reproducibility review;
- deploy once;
- verify the deployed version;
- complete final documentation and repository checks.
Adjust this sequence when the project demands it, but preserve the principle of handling foundational and expensive-to-change decisions early.
After each milestone:
- run relevant checks;
- update tests;
- update the README;
- review the persistent guidance file;
- inspect the diff;
- commit the milestone.
The project must remain deployable throughout development, but prefer local validation until implementation is complete.
The final hosted version will use:
[DEPLOYMENT_PLATFORM]
A deployment CLI is available.
Deploy from the local project only once, near the end, unless an earlier deployment is essential to validate a platform-specific behavior that cannot be reproduced locally.
Do not connect the deployment to the Git repository unless explicitly requested.
Before deploying:
- run the full test suite;
- run type-checking and linting;
- produce a clean production build;
- verify environment variables;
- verify migrations and production configuration;
- review security-sensitive settings;
- confirm the README deployment instructions.
After deploying:
- verify the live application;
- test critical flows;
- inspect obvious runtime errors;
- confirm expected API and frontend behavior;
- record the final deployment instructions and URL where appropriate.
Use tools proactively to reduce manual work.
Prefer:
- framework and package-manager CLIs;
- GitHub CLI;
- deployment CLI;
- browser automation;
- code generators;
- formatters;
- linters;
- type checkers;
- test runners;
- migration tools;
- repository inspection tools.
Use granular web searches only when needed for current technical documentation, version compatibility, deployment behavior, library maintenance, or a specific implementation obstacle.
Do not perform broad exploratory research when the supplied project context is enough.
Do not repeatedly search the same issue without changing the approach.
When an approach fails, diagnose it, choose a bounded alternative, and continue.
Proceed autonomously.
Do not ask me to:
- run ordinary commands;
- inspect routine output;
- select normal implementation details;
- manually test standard flows;
- approve reversible visual decisions;
- perform reviews that can be automated;
- copy information that available tools can retrieve.
Make reasonable assumptions and document the important ones.
Escalate only when required information, credentials, permissions, irreversible product choices, legal constraints, or external access cannot be obtained safely in any other way.
My involvement should be the exception, not the normal workflow.
The task is complete only when:
- all required functionality is implemented;
- frontend and backend behavior is tested appropriately;
- the full validation suite passes;
- the production build succeeds;
- browser-level verification has been completed where useful;
- the repository is clean;
- Git history contains meaningful incremental commits;
- no secrets or private machine details are committed;
.env.exampleis synchronized;- the README is complete and accurate;
- setup is reproducible on a clean machine;
- the project is suitable for public GitHub hosting;
- the application has been deployed when required;
- the hosted version has been verified;
- known limitations are clearly documented.
At the end, provide a concise delivery summary containing:
- what was built;
- architecture and major decisions;
- test and validation results;
- repository status;
- deployment status and URL;
- setup or operational notes;
- any known limitations;
- any unavoidable follow-up actions.
You have enough direction to begin. Review the requirements and relevant references, establish the project correctly, prioritize foundational work, and proceed.