# Small Business Website Starter — AGENTS.md > A tool-agnostic operating file for building and maintaining a small-business > website with Astro, GitHub, Cloudflare, and an AI coding agent. > > License: CC0 1.0. Copy it, change it, and use it commercially without > attribution. ## How to use this file 1. Put this file at the root of your website project and keep the name `AGENTS.md`. 2. Open the project in an AI coding tool that supports workspace instructions. 3. Say: **“Read AGENTS.md and help me set up my small-business website.”** 4. Answer the first-run questions below. The agent should write the answers into the Project Profile before it changes code or connects services. This file is designed for Codex, Claude Code, Antigravity, and similar coding agents. Integrations may be called connectors, MCP servers, plugins, apps, or tools depending on the product. Use the capabilities available in the current environment; do not assume a particular integration name exists. --- ## What you'll need before you begin You do not need a developer. You do need to own a few basic business tools. Set these up in the business owner's name and email address, not in an agency, contractor, or AI tool account. ### Required 1. **A domain name you own** Example: `yourbusiness.com`. If you do not have one, buy it from a reputable domain registrar using a business-controlled email address and payment method. Turn on multi-factor authentication and save the recovery details. The domain is the address customers type into a browser; it is one of your most important business assets. 2. **A GitHub account** GitHub stores the website source and its complete change history. A free GitHub account is normally enough for a small business website. Keep the repository private while you build it, and make sure the business owner has administrator access. 3. **A Cloudflare account** Cloudflare hosts the website, provides HTTPS, and gives you preview and production delivery. Its free plan can be a sensible starting point for a straightforward static marketing site. Check the current plan limits before adding forms, databases, paid features, or unusual traffic requirements. 4. **One paid AI coding plan** Choose **one** paid plan that gives you access to a coding agent able to read project instructions and work with files. Examples include Claude Code, Codex, Antigravity, or GitHub Copilot. You do not need all four. Pick the one that fits your budget and workflow, then use it consistently. A general-purpose free chatbot is not a replacement for a coding agent with access to your project files. The useful capability is: you can ask for a change in plain English, review the exact files changed, and approve a preview before anything goes live. 5. **A computer and a modern browser** Initial setup is much easier on a laptop or desktop. You will still check the finished website on your phone. ### Strongly recommended - A business email address separate from any employee's personal email. - A shared password manager for recovery codes and account invitations. - A second trusted business administrator on GitHub, Cloudflare, and the domain registrar. - A folder containing your logo, brand colors, approved photos, service descriptions, customer proof, and contact details. - One person with final authority to approve a preview and publish it live. ### What you do not need at the start - A traditional CMS subscription. - A web-development agency retainer. - A database or custom server. - A paid GitHub plan for a basic private website repository. - Every AI coding tool on the market. Start with the simple version. Add complexity only when a real business need appears and you can explain that need in one sentence. --- ## Read this first: the nontechnical version This setup replaces a traditional website editor with a simple, reviewable workflow: 1. You describe the business result you want in ordinary language. 2. An AI coding agent changes the website files. 3. You review a private preview link. 4. You approve the change before it goes live. You do **not** need to learn to write code. You do need to own the accounts, approve important changes, and keep recovery access to your domain, GitHub, and Cloudflare accounts. ### The five pieces, in plain English | Piece | What it does | What you should care about | | --- | --- | --- | | **Astro** | Builds the web pages from simple files. | It keeps a marketing site fast and simple. | | **Markdown** | A plain-text way to write articles and page content. | It is easy to review, copy, and keep forever. | | **GitHub** | Stores the source of the website and every approved change. | It is your backup, change history, and ownership record. | | **Cloudflare** | Publishes the website and connects it to your domain. | It handles hosting, HTTPS, and preview/live environments. | | **AI coding agent** | Translates your request into website changes. | It is your implementation partner, not the owner of the site. | ### The three rules that protect you 1. **Own the accounts yourself.** Use a business-controlled email address, not an agency's or contractor's account. 2. **Preview before publishing.** A preview is the review copy; production is the live website customers can see. 3. **Never paste a secret into chat or a website file.** Passwords, API keys, tokens, recovery codes, and billing details belong in the relevant account, not in a message to an agent. --- ## Start here: account and access checklist Complete this checklist before asking an agent to connect anything. If an account already exists, verify that the business owner has administrator access and current recovery details. ### 1. Create or confirm a business email Use an email address the business will keep even if a staff member or agency leaves. Turn on multi-factor authentication. Save recovery codes somewhere the business can access safely. ### 2. Create or confirm GitHub GitHub holds the website source. Create a GitHub account using the business email, then create a repository for the site. A repository is simply the project folder online. - Suggested private repository name: `business-name-website` - Keep it private while the site is being built. - Add a trusted second owner or administrator if appropriate. - Turn on multi-factor authentication. ### 3. Create or confirm Cloudflare Cloudflare hosts the website and connects the domain. Create the account with the business email and enable multi-factor authentication. Do not transfer domain ownership, change nameservers, or change billing just because an agent suggests it. Those actions require a human owner to read and approve the exact change. ### 4. Choose an AI coding tool Use the tool your team is comfortable with. The name of the integration differs by product: - **Codex:** look for connected apps, plugins, or MCP tools. - **Claude Code or Claude Desktop:** look for MCP servers or connectors. - **Antigravity or another coding agent:** look for integrations, plugins, or MCP support in its current documentation. The important capability is not the label. The agent needs a way to inspect the local project and, only when you approve it, interact with GitHub and Cloudflare. ### 5. Decide who can approve a launch Write down one person who can say "publish this." An agent must treat everyone else as a contributor or reviewer unless that owner explicitly delegates launch authority. --- ## The 45-minute first setup This is an owner-facing walkthrough. You can do the account steps yourself and give the copy-and-paste prompts to an agent for the technical work. ### Step A: Create the project folder Ask your agent: > I am a nontechnical business owner. Create a new Astro website project for > [BUSINESS NAME]. Keep it static and simple. Add this AGENTS.md at the project > root, create a README.md and WORKLOG.md, and do not connect or deploy anything > yet. Show me the proposed pages and the files you create. Review the proposed pages before the agent writes the site. A good launch set is usually Home, About, Services or Products, Proof or Case Studies, Resources or Blog, and Contact. Do not build every possible page on day one. ### Step B: Put the project in GitHub Ask your agent: > Inspect this project and prepare it for my GitHub repository > [OWNER/REPOSITORY]. Do not push anything until I explicitly say "push to > GitHub." Explain what will be stored there and confirm that no passwords, > keys, or private customer information are included. When you are ready, ask: > Push the approved website project to my GitHub repository. Use `main` for the > future live site and create a `dev` branch for private previews. Report the > exact repository URL and commit that was pushed. ### Step C: Connect Cloudflare to GitHub This is usually done in the Cloudflare dashboard because it grants account access. The agent may guide you, but should not silently make account-level changes. 1. In Cloudflare, open **Workers & Pages** and create a new project. 2. Choose the GitHub connection option. 3. Authorize access only to the website repository, if Cloudflare offers that choice. 4. Select the repository and set the production branch to `main`. 5. Use the build command and output directory from the project's README. For a standard Astro project, these are commonly `npm run build` and `dist`. 6. Start the first deployment. 7. Open the generated preview URL and check the homepage on a phone and a desktop browser. If the project uses a Cloudflare Worker instead of Pages, stop and ask the agent to explain why in one paragraph. A normal marketing site should not need custom runtime code just to display pages. ### Step D: Connect the real domain Only do this after the Cloudflare preview works. 1. Ask the agent to provide the exact domain connection steps for your current Cloudflare setup. 2. Log in to the company-controlled domain registrar account yourself. 3. Compare every DNS or nameserver instruction with the domain shown on screen. 4. Make the change only after you understand which domain it affects. 5. Wait for Cloudflare to confirm the domain and HTTPS are active. 6. Test both `yourdomain.com` and `www.yourdomain.com` and make sure one clearly redirects to the other. Never give an agent your registrar password or recovery codes. If you are not comfortable making the domain change, use a trusted human administrator. --- ## Copy-and-paste prompts for everyday work These prompts are intentionally written for marketers. Replace the bracketed text and send them to your agent from inside the website project. ### Change copy > Read AGENTS.md and WORKLOG.md. Update the [PAGE NAME] page so it speaks to > [AUDIENCE] about [OFFER OR PROBLEM]. Keep the primary call to action as > [ACTION]. Do not change the design system, navigation, integrations, or deploy > anything. Show me the exact copy changes and what you verified. ### Add a page > Read AGENTS.md and WORKLOG.md. Add a page for [TOPIC]. Its reader is > [AUDIENCE], and the one action I want them to take is [ACTION]. Use the > existing layout and navigation. Tell me what information you still need rather > than inventing claims, testimonials, results, or legal language. Do not > deploy. ### Publish an article > Read AGENTS.md and WORKLOG.md. Draft a blog post called [TITLE] for > [AUDIENCE]. Its main argument is [ARGUMENT]. Use only facts and examples I > provide or sources we can cite. Create it as a draft first, with a title, > description, slug, and call to action. Do not publish or deploy it. ### Fix a bug > Read AGENTS.md and WORKLOG.md. On [PAGE OR URL], [DESCRIBE WHAT YOU SEE]. > First diagnose the cause. Then make the smallest safe fix, check it at mobile > and desktop sizes, and report what changed. Do not deploy. ### Request a preview > The local changes are approved for review. Build the site, update WORKLOG.md, > commit only the approved changes, and push them to the preview branch. Verify > the preview URL when it is ready. Do not publish to production. ### Publish to the live site > I approve the previewed changes for production. Re-run the build and checks, > show me what will be published, then push the approved commit to the > production branch. Verify the live site and report the result. --- ## What to expect when you ask for a change | You ask for | A responsible agent should do | It should not do | | --- | --- | --- | | New headline | Update the relevant copy and check the page. | Change the whole brand or publish automatically. | | New service page | Ask for missing facts, then add a page using the established layout. | Invent proof, prices, or legal claims. | | New blog post | Draft it first, add metadata, and prepare a preview. | Make it live without approval. | | Add analytics | Ask for the owner-controlled account and measurement ID. | Create tracking accounts in its own name. | | Connect a form | Ask where messages go and what data is collected. | Put email-service credentials in browser code. | | "Make it look better" | Ask what feels wrong, show a focused design direction, and preserve working content. | Replace the site with a generic template. | | "Publish it" | Confirm the approved preview, build, push, and verify live. | Change DNS, billing, or unrelated settings. | --- ## The file map: where things live An Astro marketing site normally looks roughly like this: ```text your-website/ AGENTS.md # Instructions for the AI agent README.md # Human setup and maintenance notes WORKLOG.md # Recent work and what is still open package.json # Build command and dependencies public/ # Files served as-is: icons, downloads, images src/ pages/ # Website pages and URLs layouts/ # Shared page framing components/ # Reusable sections: header, footer, buttons content/ # Articles, case studies, resources in Markdown/MDX styles/ # Site-wide styling ``` You do not need to memorize this. Its purpose is to help you ask good questions: pages belong in `pages`, articles belong in `content`, and a file a visitor should download belongs in `public`. --- ## How publishing works Think of GitHub branches as two versions of the same brochure: - **`dev`** is the review copy. It can be checked privately before customers see it. - **`main`** is the approved copy. Cloudflare treats it as the live website. The agent should keep these separate. A preview is successful only when you can open the actual preview URL and verify the page, not merely because the code looks correct in a chat window. ### Your pre-publish checklist Before approving production, check: - The message is accurate and sounds like the business. - Headline, call to action, phone number, email, and links work. - The page is readable on your phone. - The page is readable on a desktop browser. - Images are not stretched, missing, or unclear. - Contact forms and booking links go to the right place. - The browser shows HTTPS (the lock icon). - The page does not include placeholder copy, internal notes, or test data. --- ## Safety red flags Pause and ask a human expert if an agent asks you to do any of these without a clear explanation: - Share a password, API token, recovery code, or a screenshot containing one. - Turn off multi-factor authentication or security protections. - Move a domain to a different registrar or account. - Change nameservers without identifying the exact domain and expected effect. - Make a repository public without your approval. - Use a personal account to own company assets. - Add tracking, cookies, a chatbot, a payment tool, or a form without explaining what visitor data is collected and where it goes. - Force-push, erase history, or delete a project to "start over." - Claim legal, accessibility, security, SEO, or conversion guarantees. The right response is: **"Explain this in plain English, tell me the risk, and give me the reversible option first."** --- ## Troubleshooting without panic | What you see | Likely meaning | What to ask the agent | | --- | --- | --- | | Preview does not update | The build may still be running or failed. | "Check the latest deployment and tell me whether it built successfully." | | Live site does not match preview | The wrong branch may be live, or a deployment has not completed. | "Confirm the production branch, latest live commit, and live URL before changing anything." | | Domain shows an error | DNS or domain connection may not be complete. | "Diagnose the domain connection. Do not change DNS until you show me the exact records and expected outcome." | | Article is missing | It may still be marked as a draft or have invalid frontmatter. | "Check the article's draft status, metadata, build output, and link." | | Contact form does nothing | The delivery destination or service may be missing. | "Tell me where form submissions are supposed to go and whether any visitor data is being stored." | | Agent says it needs a secret | It may need an approved integration credential. | "Tell me why, where it will be stored, its minimum permission, and whether there is a no-secret option." | | Something looks wrong on mobile | The layout needs responsive testing. | "Reproduce this at a mobile width, identify the CSS cause, and make the smallest fix." | --- ## Project Profile The agent maintains this section after the owner answers the first-run questions. Do not invent missing business information. - **Business name:** [NEEDS OWNER INPUT] - **Primary domain:** [NEEDS OWNER INPUT] - **Primary website goal:** [NEEDS OWNER INPUT] - **Primary audience:** [NEEDS OWNER INPUT] - **Primary call to action:** [NEEDS OWNER INPUT] - **Contact email:** [NEEDS OWNER INPUT] - **GitHub repository:** [NEEDS OWNER INPUT] - **Production branch:** `main` - **Preview branch:** `dev` - **Production URL:** [NEEDS OWNER INPUT] - **Preview URL:** [NEEDS OWNER INPUT] - **Cloudflare project:** [NEEDS OWNER INPUT] - **Analytics:** [NONE OR OWNER-SUPPLIED ID] - **Legal or regulated-industry requirements:** [NONE OR OWNER INPUT] ## First-run questions Ask these in plain language, no more than three at a time: 1. What does the business sell, and who is the ideal customer? 2. What is the single most important action a visitor should take? 3. What pages are needed at launch? 4. Does a website, domain, GitHub repository, or Cloudflare account already exist? 5. Who will update the site, and how often will content change? 6. Is the business subject to accessibility, privacy, healthcare, financial, legal, ecommerce, or other industry-specific requirements? 7. Should analytics be included? If yes, the owner must provide or approve the account and measurement ID. Summarize the answers, fill in the Project Profile, and show a short build plan before making the first material change. --- ## Default architecture Use the simplest architecture that satisfies the approved requirements: - **Astro** for the site and static build. - **Markdown or MDX** for articles, resources, case studies, and other repeatable content. - **GitHub** as the source of truth and change history. - **Cloudflare** for hosting, previews, HTTPS, and domain delivery. - **AI coding agent** as the implementation interface between the owner’s plain- language requests and the codebase. Prefer static pages. Add server-side code, databases, authentication, ecommerce, forms processing, or a traditional CMS only when a documented requirement needs them. ### A CMS is probably unnecessary when - The site is primarily service pages, location pages, case studies, articles, FAQs, and contact information. - One or a few people make planned updates. - Content can be reviewed in a preview before publication. - The owner is comfortable requesting changes through an AI agent rather than a visual page editor. ### Stop and reconsider the architecture when - Many nontechnical editors must publish independently every day. - The business needs complex editorial approvals, permissions, localization, or personalization. - The site includes accounts, sensitive customer data, payments, inventory, or other application behavior. - A regulated workflow requires specialist review or a certified platform. Explain the tradeoff and get owner approval before expanding beyond the default static architecture. --- ## Integration policy ### Capability discovery Before changing GitHub or Cloudflare, inspect the tools available in the current agent environment. 1. Prefer an authenticated official GitHub connector, app, plugin, or MCP server for repository and pull-request operations. 2. Prefer an authenticated official Cloudflare connector, plugin, or MCP server for project inspection and read-only diagnostics. 3. If an integration is unavailable, use an authenticated official CLI such as GitHub CLI or Wrangler when it is already installed and authorized. 4. If neither is available, give the owner exact dashboard instructions and pause at the step requiring human access. Do not install integrations, request broad permissions, create tokens, or alter accounts without the owner’s approval. Never claim an integration succeeded without checking the resulting state. ### Least privilege - Begin with read-only access when possible. - Request write access only for the approved task. - Limit GitHub access to the website repository. - Limit Cloudflare access to the relevant account, zone, and project. - Never expose tokens, API keys, account IDs, email credentials, or secret values in chat, terminal output, commits, screenshots, or documentation. - Store secrets only in the hosting provider’s secret store or approved local environment. Add local secret files such as `.env` to `.gitignore` before using them. --- ## Repository setup If the repository does not exist, propose the repository name and wait for owner approval before creating it. The baseline repository should include: - `AGENTS.md` — these operating instructions. - `README.md` — what the site is, how to preview it, and how deployment works. - `WORKLOG.md` — a short record of recent work and anything deliberately left undone. - `.gitignore` — dependencies, builds, local settings, logs, and secrets. - Astro source, configuration, and package lockfile. - A documented license for any reusable public template or asset. Use `main` for production and `dev` for preview unless the owner chooses another workflow. Never force-push, rewrite shared history, bypass checks, or silently change repository visibility. Before every commit: 1. Show the changed files. 2. Run the relevant build and checks. 3. Confirm no secrets or generated files are staged. 4. Use a commit message that describes the business-facing change. --- ## Astro standards - Keep the site static by default. - Use shared layouts and components for navigation, footer, metadata, and calls to action. - Store repeatable content in validated Astro content collections. - Keep page titles, descriptions, canonical URLs, social metadata, and sitemap behavior consistent. - Include one clear H1 per page and meaningful heading order. - Use semantic HTML before adding JavaScript. - Keep JavaScript optional unless interaction genuinely requires it. - Avoid unnecessary dependencies and visual-builder packages. - Optimize images and supply width, height, and useful alternative text. - Support keyboard navigation, visible focus, sufficient contrast, reduced motion, and responsive layouts. Run the production build after changes. Treat warnings, broken links, missing metadata, and accessibility failures as work to resolve—not as successful completion. --- ## Cloudflare setup Use Cloudflare’s current recommended static-site path that fits the project. Cloudflare product names and limits can change, so check current official documentation before creating the project. For a straightforward static site: 1. Connect the approved GitHub repository to Cloudflare. 2. Set the Astro build command to the command defined in `package.json`, usually `npm run build`. 3. Set the output directory to Astro’s configured build output, usually `dist`. 4. Configure `main` as production. 5. Configure `dev` or branch previews as the owner-approved preview path. 6. Add the custom domain only after the preview build passes. 7. Confirm HTTPS, redirects, caching behavior, and error pages. Use Workers only when the approved requirements need request handling, custom runtime logic, or another feature that static hosting cannot provide. Document why the Worker exists and how it deploys. The agent must not independently change DNS records, nameservers, domain registrations, account ownership, billing, security policies, or production secrets. Provide the owner with exact steps for those account-level actions. --- ## Deployment rules Deployment is an owner-controlled business action. - Never push to `dev`, publish a preview, or deploy unless the owner explicitly requests it in the current conversation. - Never push to `main` or publish to production unless the owner explicitly requests it in the current conversation. - A request to edit files is not permission to deploy them. - A request to preview is not permission to publish to production. - Do not automatically chain edit → preview → production. ### Preview workflow 1. Make only the requested changes. 2. Build and check locally. 3. Update `WORKLOG.md` with what changed and what remains. 4. When explicitly requested, commit and push to the preview branch. 5. Verify the actual preview URL on desktop and mobile. 6. Report the result and stop for owner review. ### Production workflow 1. Confirm the owner approved the exact previewed changes. 2. Check repository status and remote destination. 3. Re-run the production build and checks. 4. Commit without rewriting history. 5. Push to the production branch only when explicitly requested. 6. Verify the live domain, HTTPS, primary pages, navigation, forms or contact actions, metadata, and analytics if configured. 7. Record the deployment in `WORKLOG.md`. If a push is rejected, a build fails, or the live result differs from preview, stop and report the problem. Never force a deployment through. --- ## Content publishing Treat content as a business asset, not filler. For each page or article, confirm: - Intended audience. - Reader question or problem. - Primary takeaway. - Evidence, examples, or owner experience supporting the claim. - Primary call to action. - Title, description, slug, publish date, and draft status. Do not fabricate customer stories, testimonials, credentials, results, statistics, quotes, partnerships, awards, or legal claims. Use explicit placeholders when the owner has not supplied the information. Keep drafts unpublished until the owner approves them. Preview links should be blocked from search indexing when practical. --- ## Forms, analytics, privacy, and accessibility Do not add a form merely because a template normally has one. Decide where the submission goes, who receives it, what data is retained, and how abuse is handled before implementation. - Collect the minimum information needed. - Do not expose an email-service credential in browser code. - Add analytics only with owner approval and an owner-controlled account. - Document cookies, tracking, and third-party embeds before launch. - Do not generate legal policies from assumptions. Ask the owner to provide approved language or obtain appropriate professional advice. - Target WCAG 2.2 AA for normal marketing-site work unless the owner provides a different binding requirement. For ecommerce, healthcare, financial services, legal services, children’s services, or other regulated activity, stop and ask for the applicable business and compliance requirements before building the affected feature. --- ## Communication style The business owner should not need to speak like a developer. - Lead with the outcome and the business effect. - Translate technical choices into cost, risk, speed, ownership, and customer experience. - Recommend one option when the evidence supports it. - Explain unavoidable choices in plain language. - Ask only questions that materially change the result. - Keep progress updates short and specific. - Never imply a task is complete until it has been checked. When technical detail is useful, put the recommendation first and the detail second. --- ## Definition of done A task is complete only when: - The requested outcome is implemented. - The site builds successfully. - The changed experience has been checked at relevant screen sizes. - Navigation and keyboard behavior still work. - Metadata and links affected by the change are valid. - No secrets or unrelated files were added. - `WORKLOG.md` records the current state. - The owner is told what changed, what was verified, and what remains. - No deployment occurred without explicit permission. --- ## Owner override The owner’s explicit instructions take precedence for the current task unless they would expose credentials, destroy data, violate a binding requirement, or affect an account or system outside the authorized scope. When that happens, stop, explain the risk plainly, and ask for direction. --- ## Official references Use current official documentation rather than copying setup commands from old articles: - Astro documentation: - Cloudflare Git integration: - Cloudflare-managed MCP servers: - GitHub MCP server: - Anthropic MCP documentation: The architecture in this file is portable. The exact connector, MCP, plugin, authentication, and deployment screens will vary by agent and may change over time.