Create Project Flow

When to use this flow

Use this workflow when creating a new SiteFactory project from a reusable template or a simple manual start. A project can be an app module, miniapp, dashboard, interface, tool, website or preview.

a new app module
a new interface panel
a new miniapp
a new dashboard
a new landing page or artist page
a new project preview

Standard folder pattern

Canonical source belongs in `projects/project-name/`. The Astro shell contains only a browser preview copy for review.

Project source

projects/project-name/
  README.md
  AGENTS.md
  PROJECT_STATE.md
  DEPLOYMENT.md
  COMMANDS.md
  public/
    index.html
    styles.css
    app.js optional

Preview copy

projects/sitefactory-test/public/project-previews/project-name/
  index.html
  styles.css
  app.js optional

Template selection

Choose the smallest template that fits the module, miniapp, dashboard, interface or website. If none fits, build the simplest manual project first.

Use templates/minimal-landing for simple landing pages and content-led website starts.
Use templates/todo-list-app for functional todo-style miniapps.
If no suitable template exists, create the simplest possible module or project manually first.
Extract reusable parts into a template later only after functionality is proven.

Step-by-step flow

template or manual start -> new project -> project docs -> preview copy -> local preview -> build check -> registry update -> commit/tag -> push -> Cloudflare deploy when needed

choose project name using kebab-case
choose source template
create projects/project-name
copy template files into project public folder
adapt content, interface structure or functionality
create project docs
create preview copy inside sitefactory-test public project-previews
ensure preview folder has index.html with relative CSS and JavaScript links
verify the local preview URL works without a direct file path when possible
update dashboard
update registry
run npm run build inside projects/sitefactory-test
confirm the preview is included in dist
test local preview
commit
tag milestone if appropriate
push to GitHub
let Cloudflare deploy

Codex prompt starter

Copy this prompt and replace the placeholders.

Create a new SiteFactory project.

A project can be an app module, miniapp, dashboard, interface, tool, website or preview.

PROJECT_NAME:
PROJECT_NAME

SOURCE_TEMPLATE:
SOURCE_TEMPLATE

PROJECT_PURPOSE:
PROJECT_PURPOSE

PROJECT_TONE:
PROJECT_TONE

PROJECT_SECTIONS:
PROJECT_SECTIONS

FUNCTIONALITY:
FUNCTIONALITY

Before changing anything:
- inspect the current project structure
- read README.md
- read AGENTS.md
- read NAMING.md
- read PROJECT_STATE.md
- read the source template documentation
- check git status

Rules:
- follow NAMING.md
- preserve portability
- keep Astro only as the development and preview shell
- create canonical project source in projects/PROJECT_NAME
- create a preview copy in projects/sitefactory-test/public/project-previews/PROJECT_NAME
- update dashboard
- update registry
- run npm run build in projects/sitefactory-test
- do not deploy manually
- do not add dependencies unless explicitly required

When finished, summarize files created, files modified, preview URL, build result, git status, and exact next command.

Prompt Builder

Use Prompt Builder before this flow when an idea needs to become a structured, agent-neutral build prompt.

Prompt Builder lives at /docs/prompt-builder.html.

Review checklist

Use this before considering the project creation complete.

project or module opens locally
preview URL works
preview folder contains index.html
links are relative
build output includes the preview
naming follows NAMING.md
no unnecessary dependencies
build passes
registry is updated
git status is reviewed

Common mistakes

These mistakes make projects harder for humans and agents to maintain.

putting canonical source only inside public preview
forgetting that public preview is only a copy
forgetting that Astro dev may need a simple preview access route
creating Astro-specific templates too early
mixing button/card/panel naming
adding dependencies before proving need
forgetting registry update
forgetting build check

Next actions

Keep the workflow static until repeated friction proves a change is needed.

use this flow for the next real module, miniapp, interface, dashboard or website
improve only after repeated friction appears
keep the workflow static until it becomes painful