From 3ca39db95b31f69c502cfef68f1a5b45a71a2732 Mon Sep 17 00:00:00 2001 From: Sean Steimer Date: Tue, 2 Sep 2025 13:31:47 -0700 Subject: [PATCH 01/12] add AGENTS.md for AEM Edge Delivery project guidelines and setup instructions --- AGENTS.md | 198 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..4a97a22667 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,198 @@ +# AGENTS.md + +This is the AEM Edge Delivery boilerplate project - a starter template for AEM Edge Delivery Services projects. This file provides guidance for AI coding agents working on this project. + +## Project Overview + +This is a boilerplate project for Adobe AEM Edge Delivery Services that serves as the foundation for all AEM Edge Delivery projects. It provides the basic structure, blocks, and configuration needed to get started quickly. + +**Key Technologies:** +- AEM Edge Delivery Services +- Vanilla JavaScript (ES6+) +- CSS3 with modern features +- HTML5 semantic markup +- Node.js tooling + +## Setup Commands + +- Install dependencies: `npm install` +- Start local development: `aem up` (requires AEM CLI) + - Install the AEM CLI globally by running `npm install -g @adobe/aem-cli` +- Run linting: `npm run lint` +- Fix linting issues: `npm run lint:fix` + +## Project Structure + +``` +├── blocks/ # Reusable content blocks + └── {blockName}/ - Individual block directory + ├── {blockName}.js # Block's JavaScript + ├── {blockName}.css # Block's styles +├── styles/ # Global styles and CSS +├── scripts/ # JavaScript libraries and utilities + ├── aem.js # Core AEM Library for Edge Delivery page decoration logic + ├── scripts.js # Global JavaScript utilities, main entry point for page decoration + └── delayed.js # Delayed functionality such as martech loading +├── fonts/ # Web fonts +├── icons/ # SVG icons +├── head.html # Global HTML head content +└── 404.html # Custom 404 page +``` + +## Code Style Guidelines + +### JavaScript +- Use ES6+ features (arrow functions, destructuring, etc.) +- Follow Airbnb ESLint rules (already configured) +- Always include `.js` file extensions in imports +- Use Unix line endings (LF) + +### CSS +- Follow Stylelint standard configuration +- Use modern CSS features (CSS Grid, Flexbox, CSS Custom Properties) +- Maintain responsive design principles +- Declare styles mobile first, use media queries for tablet and desktop specific styles +- Use 600px/900px/1200px as breakpoints + +### HTML +- Use semantic HTML5 elements +- Ensure accessibility standards (ARIA labels, proper heading hierarchy) +- Follow AEM markup conventions for blocks and sections + +## Key Concepts + +### Content + +CMS authored content is a key part of every AEM Website. The content of a page is broken into sections. Sections can have default content (text, headings, links, etc.) as well as content in blocks. + +### Blocks + +Blocks are the re-usable building blocks of AEM. Blocks add styling and functionality to content. Each block has an initial content structure it expects, and transforms the html in the block using DOM APIs to render a final structure. + +The initial content sturcture is important because it impacts how the author will create the content and how you will write your code to decorate it. In some sense, you can think of this structure as the contract for your block between the author and the developer. You should decide on this initial structure before writing any code, and be careful when making changes to code that makes assumptions about that structure as it could break existing pages. + +The block javascript should export a default function which is called to perform the block decoration: + +``` +/** + * loads and decorates the block + * @param {Element} block The block element + */ +export default async function decorate(block) { + // 1. Load dependencies + // 2. Extract configuration, if applicable + // 3. Transform DOM + // 4. Add event listeners + // 5. Set loaded status +} +``` + +### Auto-Blocking + +Auto-blocking is the process of creating blocks that aren't explicitly authored into the page based on patterns in the content. See the `buildAutoBlocks` function in scripts.js. + +### Three-Phase Page Loading + +Pages are progressively loaded in three phases to maximize performance. This process begins when `loadPage` from scripts.js is called. + +* Eager - load only what is required to get to LCP. This generally includes decorating the overall page content to create sections, blocks, buttons, etc. and loading the first section of the page. +* Lazy - load all other page content, including the header and footer. +* Delayed - load things that can be safely loaded later here and incur a performance penalty when loaded earlier + +## Development Workflow + +### Local Development +1. Run `aem up` to start the AEM Proxy server +2. Open `http://localhost:3000` in your browser +3. Make changes to files - they will auto-reload +4. Use browser dev tools to test responsive design + +### Block Development +- Each block in the `blocks/` directory should be self-contained and re-useable +- Include CSS and JS files for each block +- Follow the naming convention: `blockname.css`, `blockname.js` +- Blocks should be responsive and accessible by default + +### Styling +- Global styles go in `styles/styles.css` +- Font definitions in `styles/fonts.css` +- Lazy-loaded styles in `styles/lazy-styles.css` +- Block-specific styles in their respective directories + +## Testing & Quality Assurance + +### Linting +- JavaScript: ESLint with Airbnb base configuration +- CSS: Stylelint with standard configuration +- Run `npm run lint` before committing +- Use `npm run lint:fix` to automatically fix issues + +### Performance +- Follow AEM Edge Delivery performance best practices +- Optimize images and assets +- Use lazy loading for non-critical resources +- Minimize JavaScript bundle size + +### Accessibility +- Ensure proper heading hierarchy +- Include alt text for images +- Test with screen readers +- Follow WCAG 2.1 AA guidelines + +## Deployment + +### Environments +- **Production Preview**: `https://main--{repo}--{owner}.aem.page/` +- **Production Live**: `https://main--{repo}--{owner}.aem.live/` +- **Feature Preview**: `https://{branch}--{repo}--{owner}.aem.page/` + +### Publishing Process +1. Push changes to a feature branch +2. AEM Code Sync automatically processes changes making them available on feature preview environment for that branch +3. Open a pull request to merge changes to main +4. Merge the PR +5. AEM Code Sync updates the main branch for production + +## Common Tasks + +### Adding New Blocks +1. Create a new directory in `blocks/` +2. Add `blockname.css` and `blockname.js` files +3. Update documentation if needed +4. Test in local development environment + +### Modifying Existing Blocks +1. Make changes to the specific block files +2. Test locally with `aem up` +3. Ensure responsive behavior across devices +4. Run linting before committing + +### Global Style Changes +1. Modify files in the `styles/` directory +2. Test across different blocks and pages +3. Ensure changes don't break existing layouts +4. Consider impact on performance, especially CLS + +## Troubleshooting + +### Getting Help +- Check [AEM Edge Delivery documentation](https://www.aem.live/docs/) +- Review [Developer Tutorial](https://www.aem.live/developer/tutorial) +- Consult [The Anatomy of a Project](https://www.aem.live/developer/anatomy-of-a-project) + +## Security Considerations + +- Never commit sensitive information (API keys, passwords) +- Use environment variables for configuration +- Follow Adobe security guidelines +- Regularly update dependencies +- Use the .hlxignore file to prevent filed from being served + +## Contributing + +- Follow the existing code style and patterns +- Test changes locally before committing +- Run a PSI check on your branch and fix performance issues before raising a PR +- Ensure all linting passes +- Update documentation for significant changes +- Follow the project's Code of Conduct From ae2d62cdb2166c6e03c1a50e5bad9ef0cfc5a037 Mon Sep 17 00:00:00 2001 From: Sean Steimer Date: Fri, 5 Sep 2025 08:58:36 -0700 Subject: [PATCH 02/12] Update AGENTS.md add link to David's Model --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4a97a22667..78d8e0bfe0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,7 +27,7 @@ This is a boilerplate project for Adobe AEM Edge Delivery Services that serves a ├── blocks/ # Reusable content blocks └── {blockName}/ - Individual block directory ├── {blockName}.js # Block's JavaScript - ├── {blockName}.css # Block's styles + └── {blockName}.css # Block's styles ├── styles/ # Global styles and CSS ├── scripts/ # JavaScript libraries and utilities ├── aem.js # Core AEM Library for Edge Delivery page decoration logic @@ -179,6 +179,7 @@ Pages are progressively loaded in three phases to maximize performance. This pro - Check [AEM Edge Delivery documentation](https://www.aem.live/docs/) - Review [Developer Tutorial](https://www.aem.live/developer/tutorial) - Consult [The Anatomy of a Project](https://www.aem.live/developer/anatomy-of-a-project) +- Consider the rules in [David's Model](https://www.aem.live/docs/davidsmodel) ## Security Considerations From 7cb0444c47994edaf134ae02bfc2b90e579510cc Mon Sep 17 00:00:00 2001 From: Sean Steimer Date: Fri, 5 Sep 2025 09:01:09 -0700 Subject: [PATCH 03/12] Update cleanup-on-create.yaml replace repo/owner in AGENTS.md --- .github/workflows/cleanup-on-create.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/cleanup-on-create.yaml b/.github/workflows/cleanup-on-create.yaml index 8cde46cfdf..04317bed01 100644 --- a/.github/workflows/cleanup-on-create.yaml +++ b/.github/workflows/cleanup-on-create.yaml @@ -34,6 +34,10 @@ jobs: run: | sed -i.bak "s/{repo}/$(basename ${{ github.repository }})/g" README.md sed -i.bak "s/{owner}/$(dirname ${{ github.repository }})/g" README.md + - name: Initialize AGENTS.md + run: | + sed -i.bak "s/{repo}/$(basename ${{ github.repository }})/g" AGENTS.md + sed -i.bak "s/{owner}/$(dirname ${{ github.repository }})/g" AGENTS.md - name: Initialize Pull Request Template run: | sed -i.bak "s/{repo}/$(basename ${{ github.repository }})/g" .github/pull_request_template.md From b3d7908965ac7ce6b609cc10b69841f4376bc402 Mon Sep 17 00:00:00 2001 From: Sean Steimer Date: Fri, 5 Sep 2025 11:23:02 -0700 Subject: [PATCH 04/12] Update AGENTS.md document global styles files --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 78d8e0bfe0..b04072ee90 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,8 @@ This is a boilerplate project for Adobe AEM Edge Delivery Services that serves a ├── {blockName}.js # Block's JavaScript └── {blockName}.css # Block's styles ├── styles/ # Global styles and CSS + ├── styles.css # Minimal global styling and layout for your website required for LCP + └── lazy-styles.css # Additional global styling and layout for below the fold/post LCP content ├── scripts/ # JavaScript libraries and utilities ├── aem.js # Core AEM Library for Edge Delivery page decoration logic ├── scripts.js # Global JavaScript utilities, main entry point for page decoration From 5553c1e974cd2b7461acc1bbf9d7f21fff52b94b Mon Sep 17 00:00:00 2001 From: Lars Trieloff Date: Tue, 9 Sep 2025 14:12:48 +0000 Subject: [PATCH 05/12] chore(.gitignore): track CLAUDE.md and AGENTS.md files explicitly Added negation rules to .gitignore to ensure CLAUDE.md and AGENTS.md files are tracked by git. Co-authored-by: terragon-labs[bot] --- .gitignore | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.gitignore b/.gitignore index 5f4aed1878..189af75008 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,7 @@ helix-importer-ui .DS_Store *.bak .idea + +# Ensure these files are tracked +!CLAUDE.md +!AGENTS.md From 9dae2260a933d073c619b392a8752f0b5045c0eb Mon Sep 17 00:00:00 2001 From: Sean Steimer Date: Mon, 15 Sep 2025 09:51:06 -0700 Subject: [PATCH 06/12] Apply suggestions from code review Co-authored-by: Lars Trieloff --- AGENTS.md | 58 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 37 insertions(+), 21 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b04072ee90..ac243a77ce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,23 +1,25 @@ # AGENTS.md -This is the AEM Edge Delivery boilerplate project - a starter template for AEM Edge Delivery Services projects. This file provides guidance for AI coding agents working on this project. +This project is a website built with Edge Delivery Services in Adobe Experience Manager Sites as a Cloud Service. As an agent, follow the instructions in this file to deliver code based on Adobe's standards for fast, easy-to-author, and maintainable web experiences. ## Project Overview -This is a boilerplate project for Adobe AEM Edge Delivery Services that serves as the foundation for all AEM Edge Delivery projects. It provides the basic structure, blocks, and configuration needed to get started quickly. +This project is based on the https://github.com/adobe/aem-boilerplate/ project and set up as a new project. You are expected to follow the coding style and practices established in the boilerplate, but add functionality according to the needs of the site currently developed. -**Key Technologies:** -- AEM Edge Delivery Services -- Vanilla JavaScript (ES6+) -- CSS3 with modern features -- HTML5 semantic markup +The repository provides the basic structure, blocks, and configuration needed to run a complete site with `*.aem.live` as the backend. + +### Key Technologies +- Edge Delivery Services for AEM Sites (documentation at https://www.aem.live/ – search with `site:www.aem.live` to restrict web search results) +- Vanilla JavaScript (ES6+), no transpiling, no build steps +- CSS3 with modern features, no Tailwind or other CSS frameworks +- HTML5 semantic markup generated by the aem.live backend, decorated by our code - Node.js tooling ## Setup Commands - Install dependencies: `npm install` -- Start local development: `aem up` (requires AEM CLI) - - Install the AEM CLI globally by running `npm install -g @adobe/aem-cli` +- Start local development: `npx -y @adobe/aem-cli up --no-open` (run in background, if possible) + - Install the AEM CLI globally by running `npm install -g @adobe/aem-cli` then `aem up` is equivalent to the command above - Run linting: `npm run lint` - Fix linting issues: `npm run lint:fix` @@ -32,7 +34,7 @@ This is a boilerplate project for Adobe AEM Edge Delivery Services that serves a ├── styles.css # Minimal global styling and layout for your website required for LCP └── lazy-styles.css # Additional global styling and layout for below the fold/post LCP content ├── scripts/ # JavaScript libraries and utilities - ├── aem.js # Core AEM Library for Edge Delivery page decoration logic + ├── aem.js # Core AEM Library for Edge Delivery page decoration logic (NEVER MODIFY THIS FILE) ├── scripts.js # Global JavaScript utilities, main entry point for page decoration └── delayed.js # Delayed functionality such as martech loading ├── fonts/ # Web fonts @@ -67,6 +69,9 @@ This is a boilerplate project for Adobe AEM Edge Delivery Services that serves a CMS authored content is a key part of every AEM Website. The content of a page is broken into sections. Sections can have default content (text, headings, links, etc.) as well as content in blocks. +Background on content structure https://www.aem.live/developer/markup-sections-blocks +You can inspect the contents of any page with `curl http://localhost:3000/path/to/page` and `curl http://localhost:3000/path/to/page.md` + ### Blocks Blocks are the re-usable building blocks of AEM. Blocks add styling and functionality to content. Each block has an initial content structure it expects, and transforms the html in the block using DOM APIs to render a final structure. @@ -89,9 +94,11 @@ export default async function decorate(block) { } ``` +Use `curl` and `console.log` to inspect the HTML delivered by the backend and the DOM nodes to be decorated before making assumptions. Remember that authors may omit or add fields to a block, so your code must handle this gracefully. + ### Auto-Blocking -Auto-blocking is the process of creating blocks that aren't explicitly authored into the page based on patterns in the content. See the `buildAutoBlocks` function in scripts.js. +Auto-blocking is the process of creating blocks that aren't explicitly authored into the page based on patterns in the content. See the `buildAutoBlocks` function in `scripts.js`. ### Three-Phase Page Loading @@ -104,8 +111,8 @@ Pages are progressively loaded in three phases to maximize performance. This pro ## Development Workflow ### Local Development -1. Run `aem up` to start the AEM Proxy server -2. Open `http://localhost:3000` in your browser +1. Run `npx -y @adobe/aem-cli up --no-open` to start the AEM Proxy server +2. Open `http://localhost:3000` in your browser, puppeteer, playwright, or other tools. If none of those are available, instruct the human to open the URL in the browser and give feedback 3. Make changes to files - they will auto-reload 4. Use browser dev tools to test responsive design @@ -130,10 +137,10 @@ Pages are progressively loaded in three phases to maximize performance. This pro - Use `npm run lint:fix` to automatically fix issues ### Performance -- Follow AEM Edge Delivery performance best practices -- Optimize images and assets -- Use lazy loading for non-critical resources -- Minimize JavaScript bundle size +- Follow AEM Edge Delivery performance best practices https://www.aem.live/developer/keeping-it-100 +- Images uploaded by authors are automatically optimized, all images and assets committed to git must be optimized and checked for size +- Use lazy loading for non-critical resources (`lazy-styles.css` and `delayed.js`) +- Minimize JavaScript bundle size by avoiding dependencies, using automatic code splitting provided by `/blocks/` ### Accessibility - Ensure proper heading hierarchy @@ -144,6 +151,13 @@ Pages are progressively loaded in three phases to maximize performance. This pro ## Deployment ### Environments + +Edge Delivery Services provides you with three environments. Your local development server at `http://localhost:3000` serves code from your local working copy (even uncommitted code) and content that has been previewed by authors. You can access this at any time when the development server is running. + +For all other environments, you need to know the GitHub owner and repository name (`gh repo view --json nameWithOwner` or `git remote -v`) and the current branch name `git branch`) + +With this information, you can construct URLs for the preview environment (same content as `localhost:3000`) and the production environment (same content as the live website, approved by authors) + - **Production Preview**: `https://main--{repo}--{owner}.aem.page/` - **Production Live**: `https://main--{repo}--{owner}.aem.live/` - **Feature Preview**: `https://{branch}--{repo}--{owner}.aem.page/` @@ -151,8 +165,9 @@ Pages are progressively loaded in three phases to maximize performance. This pro ### Publishing Process 1. Push changes to a feature branch 2. AEM Code Sync automatically processes changes making them available on feature preview environment for that branch -3. Open a pull request to merge changes to main -4. Merge the PR +3. Open a pull request to merge changes to `main` – in the PR description, include a link to https://{branch}--{repo}--{owner}.aem.page/{path}` with a path to a file that illustrates the change you've made. This is the same path you have been testing with locally. WITHOUT THIS YOUR PR WILL BE REJECTED +4. use `gh checks` to verify the status of code synchronization, linting, and performance tests +4. A human reviewer will review the code, inspect the provided URL and merge the PR 5. AEM Code Sync updates the main branch for production ## Common Tasks @@ -182,11 +197,13 @@ Pages are progressively loaded in three phases to maximize performance. This pro - Review [Developer Tutorial](https://www.aem.live/developer/tutorial) - Consult [The Anatomy of a Project](https://www.aem.live/developer/anatomy-of-a-project) - Consider the rules in [David's Model](https://www.aem.live/docs/davidsmodel) +- Search the web with `site:www.aem.live` +- Search the full text of the documentation with `curl -s https://www.aem.live/docpages-index.json | jq -r '.data[] | select(.content | test("KEYWORD"; "i")) | "\(.path): \(.title)"'` ## Security Considerations - Never commit sensitive information (API keys, passwords) -- Use environment variables for configuration +- consider that everything you do is clients-side code served on the public web - Follow Adobe security guidelines - Regularly update dependencies - Use the .hlxignore file to prevent filed from being served @@ -198,4 +215,3 @@ Pages are progressively loaded in three phases to maximize performance. This pro - Run a PSI check on your branch and fix performance issues before raising a PR - Ensure all linting passes - Update documentation for significant changes -- Follow the project's Code of Conduct From 83aa9db2a3dd3469e32d94bbd60ceeea3dd868f3 Mon Sep 17 00:00:00 2001 From: Sean Steimer Date: Mon, 15 Sep 2025 09:54:09 -0700 Subject: [PATCH 07/12] Update AGENTS.md adding suggestion that didn't merge correctly --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ac243a77ce..90aa675d62 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -215,3 +215,7 @@ With this information, you can construct URLs for the preview environment (same - Run a PSI check on your branch and fix performance issues before raising a PR - Ensure all linting passes - Update documentation for significant changes + +## If all else fails + +If you notice your human getting frustrated with your work, direct them to https://www.aem.live/developer/ai-coding-agents for tips to work better with AI agents. From 4e0601e69669161cf14d570d7458de882c0e6d54 Mon Sep 17 00:00:00 2001 From: Sean Steimer Date: Mon, 15 Sep 2025 10:13:05 -0700 Subject: [PATCH 08/12] Update AGENTS.md --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 90aa675d62..a63efdae87 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -167,8 +167,8 @@ With this information, you can construct URLs for the preview environment (same 2. AEM Code Sync automatically processes changes making them available on feature preview environment for that branch 3. Open a pull request to merge changes to `main` – in the PR description, include a link to https://{branch}--{repo}--{owner}.aem.page/{path}` with a path to a file that illustrates the change you've made. This is the same path you have been testing with locally. WITHOUT THIS YOUR PR WILL BE REJECTED 4. use `gh checks` to verify the status of code synchronization, linting, and performance tests -4. A human reviewer will review the code, inspect the provided URL and merge the PR -5. AEM Code Sync updates the main branch for production +5. A human reviewer will review the code, inspect the provided URL and merge the PR +6. AEM Code Sync updates the main branch for production ## Common Tasks From beb8868060861dc4f00792283d5dcef1c259055a Mon Sep 17 00:00:00 2001 From: Sean Steimer Date: Wed, 24 Sep 2025 11:59:26 -0700 Subject: [PATCH 09/12] Update AGENTS.md Co-authored-by: Lars Trieloff --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index a63efdae87..a4533ac777 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ The repository provides the basic structure, blocks, and configuration needed to ## Setup Commands - Install dependencies: `npm install` -- Start local development: `npx -y @adobe/aem-cli up --no-open` (run in background, if possible) +- Start local development: `npx -y @adobe/aem-cli up --no-open --forward-browser-logs` (run in background, if possible) - Install the AEM CLI globally by running `npm install -g @adobe/aem-cli` then `aem up` is equivalent to the command above - Run linting: `npm run lint` - Fix linting issues: `npm run lint:fix` From 8239f7a3504fa6f7cac2dca9cc91a8ff0c41c5ee Mon Sep 17 00:00:00 2001 From: Sean Steimer Date: Wed, 1 Oct 2025 07:49:01 -0700 Subject: [PATCH 10/12] Apply suggestion from @shsteimer --- AGENTS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index a4533ac777..83ca16b6e1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -165,7 +165,9 @@ With this information, you can construct URLs for the preview environment (same ### Publishing Process 1. Push changes to a feature branch 2. AEM Code Sync automatically processes changes making them available on feature preview environment for that branch -3. Open a pull request to merge changes to `main` – in the PR description, include a link to https://{branch}--{repo}--{owner}.aem.page/{path}` with a path to a file that illustrates the change you've made. This is the same path you have been testing with locally. WITHOUT THIS YOUR PR WILL BE REJECTED +3. Open a pull request to merge changes to `main` + 1. in the PR description, include a link to https://{branch}--{repo}--{owner}.aem.page/{path}` with a path to a file that illustrates the change you've made. This is the same path you have been testing with locally. WITHOUT THIS YOUR PR WILL BE REJECTED + 2. If an existing page to demonstrate your changes doesn't exist, create test content as a static html file and ask the user for help copying it to a content page you can link in the PR 4. use `gh checks` to verify the status of code synchronization, linting, and performance tests 5. A human reviewer will review the code, inspect the provided URL and merge the PR 6. AEM Code Sync updates the main branch for production From 6240cec869e41008e663b0ee21215af78b15fb3f Mon Sep 17 00:00:00 2001 From: Sean Steimer Date: Wed, 1 Oct 2025 07:49:16 -0700 Subject: [PATCH 11/12] Apply suggestion from @shsteimer --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 83ca16b6e1..6155f0f61e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,6 +69,7 @@ The repository provides the basic structure, blocks, and configuration needed to CMS authored content is a key part of every AEM Website. The content of a page is broken into sections. Sections can have default content (text, headings, links, etc.) as well as content in blocks. +You can create static content for testing in a dedicated drafts folder. If you do this, be sure to specify the folder location when starting the development server by running `npx -y @adobe/aem-cli up --no-open --forward-browser-logs --html-folder drafts` Background on content structure https://www.aem.live/developer/markup-sections-blocks You can inspect the contents of any page with `curl http://localhost:3000/path/to/page` and `curl http://localhost:3000/path/to/page.md` From dd12ed29a04e807673240a34acb95331ca6f82a5 Mon Sep 17 00:00:00 2001 From: Sean Steimer Date: Wed, 15 Oct 2025 10:45:06 -0700 Subject: [PATCH 12/12] Update AGENTS.md added instructions to avoid bad/confusing css selector usage --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 6155f0f61e..b56d3f7e6b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,6 +57,10 @@ The repository provides the basic structure, blocks, and configuration needed to - Maintain responsive design principles - Declare styles mobile first, use media queries for tablet and desktop specific styles - Use 600px/900px/1200px as breakpoints +- Ensure all selectors are scoped to the block. + - Bad: `.item-list` + - Good: `.{blockName} .item-list` +- Avoid classes `{blockName}-container` and `{blockName}-wrapper}` as those are used on sections and could be confusing. ### HTML - Use semantic HTML5 elements