How To Start A Project

Use this guide when starting a new Codex-assisted project.

The goal is to make every new project start with the same operating rules:

• Work locally first.
• Use the same standard directory structure in every project.
• Keep only important human-facing launch commands, such as run.bat or start-server.bat, at the project root.
• Use OneDrive only as a controlled non-data sync target.
• Load the standard documentation, changelog, and handover templates.
• Follow VERSION_CONTROL.md for app, module, script, and prompt versions.
• Capture a short product overview before implementation starts.
• Keep secrets and generated data out of source and OneDrive unless explicitly requested.

Before You Start

Decide:

• Local project folder.
• Whether a OneDrive folder exists or is required.
• Whether the project will create generated data, raw API responses, exports, or final output files.
• Where secrets live, such as API keys, database credentials, or .env files.
• Whether the project should be documented in QDG KB, following AGENTS.md. Do not ask for a documentation cadence after every request.
• Whether the project has any existing scripts or prompts that need archive/version handling.

Mandatory Setup Interview

Do not begin project implementation by silently choosing defaults. If the project does not already contain recorded setup answers, the agent must ask these questions, wait for the answers, and record them. Use structured question controls when the client provides them; otherwise display the exact choices as Markdown.

Ask the documentation decision first:

Should this project be documented in QDG Knowledge Base? Y/N

Then ask for the technology selection:

What language or framework will this project use? Select all that apply.

- [ ] Python
- [ ] .NET
- [ ] Django
- [ ] Other — enter the language/framework:

Django may be selected together with Python. A likely answer inferred from existing files may be offered as an editable recommendation, but it must still be confirmed. Record the final selection in documents\PROJECT_SETUP.md with the project name, setup date and Confirmed by: Robert.

If QDG KB documentation is Yes, then ask for the editable QDG KB project name and initial page selection exactly as defined in AGENTS.md. If it is No, record that decision as directed there and do not create Knowledge Base pages.

These are one-time setup prompts. Do not ask them again after the answers are recorded unless Robert asks to change the project setup.

Standard Project Structure

Every project must start with this structure. Create the standard directories even when some are initially empty, so people and agents do not have to rediscover where files belong.

[ProjectRoot]\
  AGENTS.md
  .gitignore
  run.bat                         # if there is one primary workflow
  start-server.bat                # if the project runs a server
  stop-server.bat                 # if the server needs a supported stop command
  changelog\
    CHANGELOG.md
  data\
    .gitkeep
  documents\
    PROJECT_SETUP.md
    README.md
    VERSION_CONTROL.md
  final-files\
  handover\
    HANDOVER.md
  src\
    README.md                      # only when source-specific guidance is useful
  tests\
    data\                          # safe synthetic fixtures only
  tools\
  working\

Use one working\ directory; do not create a second working area under a different spelling or name. Add project-specific directories only when their role cannot fit this structure, and document them in documents\README.md.

Directory responsibilities

Path	Required purpose
Project root	Important entry points and files a person needs immediately: AGENTS.md, .gitignore, dependency/packaging metadata, and significant launch wrappers such as run.bat, start-server.bat, stop-server.bat or an equivalent supported command. Do not fill the root with experiments or one-off helpers.
changelog\	Current changelog and, where the project requires them, archived changelog versions.
data\	Local input, raw, intermediate, downloaded, exported or generated data. Treat it as local working data and exclude it from GitHub. Do not store credentials here.
documents\	Project overview, user/operations documentation, version-control rules, architecture and durable general documentation.
final-files\	Reviewed final process outputs that are the project's accepted source of truth. Do not mix drafts into this directory. Decide and document their backup location. Track only small, non-sensitive files in Git; keep large, generated, licensed, private or production-data outputs out of GitHub.
handover\	Current handover and any deliberately retained historical handovers.
src\	Maintained application/source files such as .py modules. Source-specific Markdown may live beside the code when it explains that code; general, user or operational documentation belongs in documents\.
tests\	Automated tests, test support code and safe synthetic fixtures. Never commit copied production data, secrets or private personal data as test fixtures.
tools\	Small, narrowly scoped utilities used to inspect, convert, migrate or repair project material. A reusable supported workflow belongs in src\ or a root launch wrapper; a truly temporary experiment belongs in working\.
working\	Scratch work, builds, temporary scripts, investigations, generated test results and incomplete outputs. Exclude it from GitHub and do not treat anything here as authoritative.

Root-file rule

Keep a .bat, .ps1, executable script or command file at the project root only when it is a significant, supported entry point that a user is expected to run. Prefer stable, obvious names:

• run.bat for the primary workflow;
• start-server.bat and stop-server.bat for a service;
• setup.bat only when repeatable environment setup is genuinely required.

Place the real implementation in src\ and make the root wrapper small. Small maintenance utilities belong in tools\; experiments belong in working\. Document every supported root command in documents\README.md.

Git and backup defaults

At minimum, initialise .gitignore so the contents of these local work areas are not committed:

#Local data and scratch work
data/*
!data/.gitkeep
working/*
!working/.gitkeep

#Generated or private test material; safe synthetic fixtures may remain tracked
tests/data/private/
tests/data/generated/

Do not automatically ignore all of final-files\: it is the accepted source-of-truth area and its contents need an explicit project decision. Record in documents\README.md whether each type of final file is tracked in Git, backed up to an approved non-Git location, or regenerated from another authoritative source. Git is not a backup for large data or secrets.

Standard Project Files

Every project should start with these templates loaded or copied into the project:

• AGENTS.md
• PROJECT_DOCUMENTATION_TEMPLATE.md
• CHANGELOG_TEMPLATE.md
• HANDOVER_TEMPLATE.md
• VERSION_CONTROL.md

Copy-Paste Kickoff Prompt

Use this prompt at the start of a new project:

This is a new project.

Project name:
[PROJECT NAME]

Local project folder:
[LOCAL PROJECT PATH]

OneDrive folder, if required:
[ONEDRIVE PATH OR "none for now"]

Product overview:
[Write 2-3 sentences explaining what the product does, what input it uses, what output it creates, and who/what uses it.]

Before implementation, ask and wait for my answers to the mandatory setup interview in AGENTS.md:
1. Should this project be documented in QDG Knowledge Base? Y/N
2. What language/framework will it use: Python, .NET, Django, and/or Other?
3. If QDG KB is Yes, what project name and initial pages should be used?

Record the confirmed answers in documents\PROJECT_SETUP.md and documents\QDG_KB.md. Do not skip
the questions, and do not ask them again after the decisions are recorded.

Operating rules:
- Work only in the local project folder during normal development.
- Create and preserve the standard directories: changelog, data, documents, final-files, handover,
  src, tests, tools, and one working directory.
- Keep only significant supported run/start/stop wrappers at the project root. Put maintained code
  in src, small utilities in tools, and experiments/build work in working.
- Keep data and working contents out of GitHub. Use only safe synthetic test fixtures in Git.
- Treat final-files as reviewed sources of truth and explicitly document how they are versioned or
  backed up; do not assume large, generated, private or production-data outputs belong in Git.
- If a OneDrive folder is provided, use it only as a controlled sync target.
- Do not sync to OneDrive unless I explicitly ask or we are ending the session.
- When syncing to OneDrive, copy only non-data files by default: source code, config templates, scripts, prompts, documentation, changelog, and handover.
- Do not copy generated data, working files, final outputs, raw API responses, exports, credentials, `.env`, or `db.json` unless I explicitly ask.
- Do not store secrets in source code, documentation, config templates, or OneDrive.
- Do not ask after each request whether documentation should be updated. During routine iteration,
  leave documentation, changelog, handover, and version snapshots unchanged.
- Update them after significant work, when I explicitly request a handover, or as part of a
  meaningful push/delivery. Consolidate related changes into one update.
- Follow VERSION_CONTROL.md for all app/module/script/prompt versions.
- Scripts and prompts must include an internal version header/comment.
- Before editing an existing version-controlled file, archive the previous version under the relevant archive folder, for example prompts\archive\stewards_prompt_v1.0.0.txt.
- Keep active user filenames stable, for example prompts\stewards_prompt.txt stays prompts\stewards_prompt.txt after version updates.

Please initialise the project using these standard templates:
- AGENTS.md
- PROJECT_DOCUMENTATION_TEMPLATE.md
- CHANGELOG_TEMPLATE.md
- HANDOVER_TEMPLATE.md
- VERSION_CONTROL.md

Create or update:
- the standard changelog, data, documents, final-files, handover, src, tests, tools, and working
  directories
- a project-root .gitignore protecting data and working contents
- documents\PROJECT_SETUP.md with the confirmed language/framework and setup details
- documents\README.md from the documentation template
- changelog\CHANGELOG.md from the changelog template
- handover\HANDOVER.md from the handover template
- documents\VERSION_CONTROL.md or an equivalent project version-control document from VERSION_CONTROL.md

Please also:
- inspect the workspace before editing
- create the required standard folder structure without inventing duplicate working/final folders
- identify likely modules/config/prompts/scripts needed
- keep important supported launch wrappers at the root and document them
- add version headers/comments to any created scripts and prompts
- archive previous versions before editing existing scripts, prompts, or modules
- ask only essential questions
- make conservative assumptions where safe
- verify any created code or scripts
- finish with a concise summary of what was created and what still needs my decision

Optional Extra Questions

If the project is data/API/database related, answer these up front where possible:

• What source database/table/file is used?
• What are the key input fields?
• What output fields are required?
• Is there a target table or write-back step?
• Should generated outputs be reviewed before write-back?
• What API/model/provider should be used?
• Where is the API key stored?
• Are raw responses or cost/usage records required?

If the project uses OneDrive:

• Is OneDrive backup-only, or should it mirror source files?
• Should generated data ever be copied?
• Are there files/folders that must always be excluded?

Handover Or Push Checklist

Use this when requesting a handover or preparing a meaningful push. Significant work should trigger the same review without asking after every individual request:

Prepare the handover or push:
- update documentation, changelog, and handover for this logical body of work
- create dated/versioned snapshots if this project uses them
- archive previous script/prompt/module versions where files changed
- confirm active filenames stayed stable while version headers were updated
- verify the current commands still work
- sync non-data files to OneDrive if a OneDrive folder is configured
- do not sync generated data, final outputs, raw responses, or secrets unless explicitly requested

Good Product Overview Examples

Example 1:

This project normalises trainer and jockey names from QDB into structured racing database fields. It reads names and country context from the database, calls an LLM through OpenRouter, and writes reviewable CSV output with parsed name fields, notes, cost, and raw response references.

Example 2:

This project converts long steward report text into short controlled comments for racing database review. It exports source rows from QDB, batches them through OpenRouter, validates the returned text, and creates final CSV files for review or database update.

Example 3:

This project creates a local reporting tool for comparing generated racing text against existing database values. It reads exported CSV files, builds review tables and summary metrics, and produces local-only reports for manual QA.