Build your first page

# Website working agreements

This project follows the website brief and acceptance criteria we have agreed with its owner. Use the existing technology choices unless a concrete requirement calls for a change.

## How to work

- For a substantial feature, explain the proposed changes and verification plan before implementing it. Complete authorized local work in small, reviewable stages.
- Read the files relevant to the task. Keep unrelated pages and configuration intact.
- Explain new technical terms in plain language when reporting to the owner.
- Use the repository's website-design, clean-code, website-testing and website-security skills when their workflows apply.
- Record important decisions and unresolved content in the project's notes. Do not invent business facts, endorsements or publishing rights.

## Verification

- Inspect package.json to find the actual build, type-check and test commands. Do not invent a successful check or create a meaningless test just to make a command pass.
- Run checks appropriate to the change. Local tests use disposable fixtures and have no production access; run them and repair failures caused by the requested change without asking at every step.
- Verify visitor interactions in a browser when browser tools are available. Report checks that remain unavailable or incomplete.
- Show the owner a working local preview and summarise changed behaviour, evidence and remaining limitations.

## Credentials and publication

- Keep API keys and other secrets out of browser code, prompts, logs and Git. Store local secrets in ignored files or the chosen secret store.
- Local build and test work is authorized. Publishing the site, sending a real message, processing a payment or changing production data requires the owner's authorization for that action.
- Preserve a recoverable working version before release. Describe how to restore it.

These are starter agreements for a new tutorial project. Adapt them to the owner's actual requirements and existing authorization.

---
name: website-design
description: Develop or refine a website's visual direction and responsive interface from its brief, content and existing design. Use for page design or visual implementation.
---

Read the website brief and any existing design notes relevant to the requested page. Work within the user's brand, content and technology choices.

When establishing a new direction, propose typography, a small colour palette, a spacing rhythm and a sample page. Explain how these choices support the audience and main visitor action. Use real content to judge hierarchy and line lengths.

Implement reusable elements for navigation, headings, buttons and repeated content. Give primary actions a clear visual hierarchy. Preserve visible keyboard focus, readable contrast and usable labels. Design narrow screens alongside desktop screens; check long headings, navigation and tap targets in a browser.

Use semantic HTML before adding custom interaction. Keep motion optional and respect reduced-motion preferences. Use assets with known permission to publish; record their sources. Do not invent client testimonials, achievements or business facts.

Before expanding a design across all pages, show the first complete page at desktop and mobile widths. Describe the main design decisions and any unresolved content. When a browser tool is unavailable, report that visual verification is still pending.

---
name: clean-code
description: Implement or refactor website code into understandable components using the project's existing stack and conventions. Use for website implementation or maintainability work.
---

Read the relevant files and package scripts before choosing an implementation. Preserve working behaviour outside the requested change. Prefer the existing stack and dependencies when they meet the need.

Keep page content separate from repeated layout where that makes editing easier. Name components, variables and functions for their purpose. Use shared components for repeated navigation and page elements; avoid abstraction for a single trivial use.

Handle empty, invalid, loading and error states for interactions that need them. Use native browser controls and semantic HTML when they serve the interaction. Avoid fake form submission, simulated success messages and dead links.

Use type checking and the project's formatting or lint rules where configured. When adding a package, explain its purpose and any new maintenance or runtime requirements. Keep generated build output, dependencies and local environment files out of version control.

Run the existing checks relevant to the change, including a production build when output can change. Summarise changed behaviour, verification results and remaining limits. Explain the main files in plain language so a beginner can find and edit their content.

---
name: website-testing
description: Verify website changes through visitor journeys, appropriate automated tests and browser checks. Use when testing a website, investigating a failure or preparing a release.
---

Start from the brief and observable acceptance criteria. Inspect existing test and build commands; do not assume that a script exists. Choose checks based on the changed behaviour and the cost of failure.

Exercise the main visitor journey and affected links, navigation and forms. Include invalid input and relevant error states. For a contact form, verify actual delivery in the agreed test destination before reporting that it works. For an email link, explain that it opens the visitor's configured email app and does not send a message automatically.

Check narrow and wide screens in a browser. Include keyboard navigation, visible focus, accessible names, zoom and horizontal overflow. Automated accessibility results complement these manual checks and do not establish complete accessibility conformance.

Add automated tests for important behaviour or demonstrated regressions. Test observable outcomes and meaningful failure cases; avoid tests that merely repeat the implementation or match incidental wording. Use disposable test data and local fixtures. Never send real messages, charge payments or alter production data without the user's authorization.

Reproduce a failure, fix its cause and rerun affected checks. Report commands run, results, browser checks performed and anything not checked. A successful build shows that the site can be generated; verify visitor behaviour separately. Never report a check as passed when it was skipped or unavailable.

---
name: website-security
description: Review a website's secrets, dependencies, inputs, permissions and deployment configuration, and repair scoped security findings. Use for requested security review or release preparation.
---

Identify the site's relevant surfaces: static pages, forms, backend routes, authentication, third-party scripts and stored data. Scope review to the actual architecture and authorized environment.

Keep credentials out of browser code, logs, prompts and Git. Distinguish build-time public configuration from server secrets. If a key was committed or exposed, stop using it, explain that deleting the file does not revoke the key, and have the owner revoke or rotate it before further use. Do not print the credential in your report.

Inspect applicable dependency advisories and assess whether the affected package and vulnerable behaviour are used. Repair within the project's compatible versions and rerun affected checks. Avoid automatic forced upgrades that may break the website.

For backend interactions, validate inputs on the server, encode output appropriately, and check authentication and authorization separately. Consider abuse controls for public forms or AI endpoints. An OpenAI API key belongs on the server; publishing a static site does not provide a secret server environment.

Check HTTPS and applicable security headers at the actual hosting layer. Collect only the data the feature needs, and explain its destination and retention. Do not claim legal compliance from a code scan.

Report each finding with its location, plausible impact, fix and verification. State review scope, tools used, unresolved findings and inaccessible surfaces. A clean scan is evidence about that scan's scope, not a guarantee that the website has no vulnerabilities. Do not scan third-party systems or deploy changes outside the authorized task.