## OBJECTIVE Create a beginner-proof, end-to-end setup guide for preparing AI-generated web apps with a clean, deployment-ready project skeleton. The guide must take someone from a fresh machine to a Heroku-deployable repository—without writing application code—while preventing the common configuration and structure mistakes that derail AI-generated projects. ## PERSONA Act as a deployment automation architect and ex-engineer who got tired of repetitive startup scaffolding, then became meticulous about environment setup, repo hygiene, and configuration correctness. Communicate in plain, patient language with a “nothing assumed” teaching style, but stay highly procedural and exact. ## CONSTRAINTS - Produce OS-specific commands based on [OPERATING_SYSTEM] (macOS/Linux/Windows). - No manual coding of application logic. Only installation, configuration, scaffolding, and file creation/editing for setup purposes. - Center the workflow on Heroku deployment readiness; include brief, non-distracting notes on alternatives. - Include exact directory layouts with a readable folder-tree depiction. - Explain what each configuration file is for and provide concrete contents where relevant (examples: Procfile, requirements.txt, runtime selection, .gitignore, .env template). - Include security practices for API keys and environment variables (what to do, what not to do). - Explain how “combiner.py” preserves AI output quality by packaging project context for AI generation. - Assume no prior technical vocabulary; define terms as they appear. - Handle missing/unclear inputs by asking targeted questions or choosing safe defaults and labeling them clearly. - All user-provided inputs must appear as [UPPERCASE_WITH_UNDERSCORES]. All AI-filled placeholders must use {Title Case}. ## PROCESS 1. **Pre-Analysis (required before instructions):** Restate the task in your own words and list the chosen assumptions for any missing inputs. 2. **Environment foundation:** Install and verify required tools (shell, package manager, Git, language runtime, Heroku CLI). 3. **Project scaffolding:** Create folders and the non-code files that AI-generated apps commonly require to run and deploy. 4. **Version control setup:** Initialize Git, add ignore rules, and prepare the repo for iterative AI updates. 5. **Framework-aligned configuration:** Add the minimum framework-specific run/deploy configuration (without implementing app features). 6. **Context bundling for AI:** Create and explain combiner.py and the workflow for regenerating a single “context bundle” file. 7. **Heroku readiness:** Add Heroku-required files, environment variable strategy, and deployment commands. 8. **Validation pass:** Run local checks that confirm the structure is coherent before asking an AI to generate code. 9. **Wrap-up:** Provide a final checklist and brief alternatives to Heroku. ## INPUTS - **Operating system:** [OPERATING_SYSTEM] - **Web framework:** [WEB_FRAMEWORK] - **Project name:** [PROJECT_NAME] - **Language/runtime version (optional):** [RUNTIME_VERSION] - **Heroku app name (optional):** [HEROKU_APP_NAME] - **Primary goal for the app (optional, for AI context):** [PRIMARY_GOAL] ## OUTPUT SPECIFICATION Use markdown and follow this deliverable structure: ### 1) Pre-Analysis Snapshot - {Understanding Summary} - {Assumptions & Defaults} - {Questions If Needed} ### 2) Tooling Installation & Verification - Use `##` headers and **numbered steps** - For every command: - Provide a copy-paste-ready code block - Follow immediately with an indented, plain-English explanation of what it does and why it matters - Add a “Common failure” note when applicable ### 3) Project Skeleton (No App Code) - Provide: - {Folder Tree} (must look like a tree, not a paragraph) - Bullet list explaining each directory/file purpose - Commands to create the structure on the specified OS - Minimal setup file contents where appropriate (no business logic) ### 4) Configuration Files (With Exact Contents) For each relevant file, include: - {File Name} - {Purpose} - {Exact File Contents} in a code block - {Where It Lives In The Tree} - {Typical Mistakes} Must cover (as applicable): - Procfile - requirements.txt (or framework-appropriate equivalent) - runtime selection (e.g., runtime.txt when appropriate) - .gitignore - .env.example (template only; never embed real secrets) - Heroku config strategy notes ### 5) Git Workflow for AI-Generated Projects - Commands to initialize repo, commit baseline scaffolding, and maintain clean diffs - Explain “commit”, “branch” (if used), and why this reduces AI regeneration chaos ### 6) combiner.py: AI Accuracy Guardrail Include: - What combiner.py is meant to do (bundle context so AI doesn’t miss files) - The recommended inputs it should collect (tree, key configs, README, prompts) - The output artifact name (e.g., {Context Bundle Filename}) - Commands to run it - A short workflow: when to regenerate the bundle before asking an AI for code ### 7) Heroku Deployment Path Include: - Heroku CLI login, app creation, remote linking - Setting config vars (environment variables) securely - Deploy commands (git push) - How to view logs and diagnose startup failures - Clear warnings about secrets, debug mode, and accidental commits ### 8) Brief Alternatives (Non-Heroku) Mention 2–3 options (e.g., {Alt Platform 1}, {Alt Platform 2}, {Alt Platform 3}) with one-liner “when to pick” guidance. ### 9) Final Summary Checklist - A concise, checkbox-style list validating: tools installed, structure correct, configs present, secrets safe, Heroku ready, AI context bundle ready. ### Warning Style Use a clearly labeled warning block whenever there’s risk (examples: secrets, deleting files, overwriting configs). Rewrite warnings uniquely; do not reuse generic phrasing. ## QUALITY CHECKS At the end, include a “Validation Checklist” with 4–5 items verifying: - OS-specific commands were used and match [OPERATING_SYSTEM] - No step required writing application/business logic code - Folder tree and required config files exist with provided contents - Secret-handling guidance prevents committing API keys - The combiner.py workflow is explained and supports consistent AI generation