@synapta/skills 0.1.1 → 0.2.0

package/skills/repo-bootstrap/assets/scoped/cli.md

@@ -0,0 +1,83 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+{{SETUP_INSTRUCTIONS}}
+{{CLI_FRAMEWORK_LINE}}
+{{BUILD_OUTPUT_LINE}}
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+{{BUILD_LINE}}
+{{RUN_LINE}}
+{{TEST_LINE}}
+{{LINT_LINE}}
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+{{CLI_FRAMEWORK_CONVENTION_LINE}}
+- Provide `--help` for all commands and subcommands
+- Use `--version` to display version information
+- Exit codes: 0 = success, 1 = general error, 2 = usage error
+- Output: structured (JSON) for scripts, human-readable for interactive
+- Errors: write to stderr, not stdout
+- Progress: show for long-running operations
+- Interactive prompts: support non-interactive mode with flags
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Validate all file paths and prevent directory traversal
+- Never execute user-provided code without explicit confirmation
+- Sensitive data: never log or display in plain text
+- Config files: validate schema and permissions
+- Network operations: timeout and retry with backoff
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] `--help` text is clear and accurate
+- [ ] `--version` displays correct version
+- [ ] Exit codes are correct
+- [ ] Errors go to stderr
+- [ ] Long operations show progress
+- [ ] Works in non-interactive mode
+- [ ] Tests cover main workflows
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+{{CLI_FRAMEWORK_DOCS_LINE}}
+- Check existing commands for patterns
+- Test with `--help` to ensure clarity
+- Check root AGENTS.md for project conventions
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/concourse.md

@@ -0,0 +1,196 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Pipeline configuration
+{{PIPELINE_COUNT_LINE}}
+{{TASKS_LINE}}
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START structure -->
+## Directory structure
+```
+ci/
+  pipeline.yml          → Main pipeline definition
+  pipeline-*.yml        → Additional pipelines (optional)
+  tasks/
+    build.yml           → Task definitions
+    test.yml
+    deploy.yml
+  scripts/
+    build.sh            → Task scripts
+    test.sh
+```
+<!-- AGENTS-GENERATED:END structure -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Pipeline conventions
+- **Resources first**: Define all resources at top of pipeline
+- **Jobs reference resources**: Use `get:` and `put:` for resource I/O
+- **Tasks are reusable**: Define tasks in separate files under `ci/tasks/`
+- **Params over hardcoding**: Use `((params))` for configuration
+- **YAML anchors**: Use anchors for repeated configuration
+
+### Naming conventions
+| Type | Convention | Example |
+|------|------------|---------|
+| Resource | kebab-case | `source-code`, `docker-image` |
+| Job | kebab-case with verb | `build-app`, `deploy-staging` |
+| Task | kebab-case | `run-tests`, `push-image` |
+| Param | snake_case | `docker_repo`, `deploy_env` |
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START patterns -->
+## Common patterns
+
+### Basic pipeline structure
+```yaml
+resources:
+  - name: source-code
+    type: git
+    source:
+      uri: ((git_uri))
+      branch: main
+
+  - name: app-image
+    type: registry-image
+    source:
+      repository: ((docker_repo))
+
+jobs:
+  - name: build-and-test
+    plan:
+      - get: source-code
+        trigger: true
+      - task: run-tests
+        file: source-code/ci/tasks/test.yml
+      - task: build-image
+        privileged: true
+        config:
+          platform: linux
+          image_resource:
+            type: registry-image
+            source: {repository: concourse/oci-build-task}
+          inputs:
+            - name: source-code
+          outputs:
+            - name: image
+          run:
+            path: build
+      - put: app-image
+        params:
+          image: image/image.tar
+```
+
+### Task definition (ci/tasks/test.yml)
+```yaml
+platform: linux
+
+image_resource:
+  type: registry-image
+  source:
+    repository: node
+    tag: "20"
+
+inputs:
+  - name: source-code
+
+run:
+  path: /bin/sh
+  args:
+    - -c
+    - |
+      cd source-code
+      npm ci
+      npm test
+```
+
+### Multi-environment deployment
+```yaml
+jobs:
+  - name: deploy-staging
+    plan:
+      - get: source-code
+        passed: [build-and-test]
+        trigger: true
+      - task: deploy
+        file: source-code/ci/tasks/deploy.yml
+        params:
+          ENVIRONMENT: staging
+
+  - name: deploy-production
+    plan:
+      - get: source-code
+        passed: [deploy-staging]
+      - task: deploy
+        file: source-code/ci/tasks/deploy.yml
+        params:
+          ENVIRONMENT: production
+```
+
+### Using across step for parallel deploys
+```yaml
+- across:
+    - var: region
+      values: [us-east-1, eu-west-1, ap-southeast-1]
+  task: deploy-region
+  file: ci/tasks/deploy.yml
+  params:
+    REGION: ((.:region))
+```
+<!-- AGENTS-GENERATED:END patterns -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Store secrets in **Vault** or **CredHub**, never in pipeline YAML
+- Use **((params))** syntax for all sensitive values
+- **Privileged containers** only for image building (oci-build-task)
+- Pin **resource versions** for reproducibility
+- Use **webhook tokens** with secrets for triggers
+- Review **fly set-pipeline** changes before applying
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] Pipeline validates: `fly validate-pipeline -c pipeline.yml`
+- [ ] Resources have appropriate `check_every` intervals
+- [ ] Tasks are defined in separate files (not inline)
+- [ ] Secrets use ((param)) syntax, not hardcoded
+- [ ] Jobs have appropriate `passed:` constraints
+- [ ] Triggers are on correct resources only
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Concourse docs: https://concourse-ci.org/docs.html
+- Resource types: https://resource-types.concourse-ci.org/
+- Pipeline examples: https://concourse-ci.org/examples.html
+- Validate locally: `fly validate-pipeline -c pipeline.yml`
+- Check existing pipelines in this repo for patterns
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/ddev.md

@@ -0,0 +1,68 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+DDEV local development environment configuration. **Use the `typo3-ddev` skill** for setup and multi-version testing.
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+| File | Purpose |
+|------|---------|
+| `config.yaml` | Main DDEV configuration |
+| `docker-compose.*.yaml` | Custom service overrides |
+| `commands/host/` | Host-side custom commands |
+| `commands/web/` | Container-side custom commands |
+| `.env` | Environment variables |
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Common Commands
+| Task | Command |
+|------|---------|
+| Start | `ddev start` |
+| Stop | `ddev stop` |
+| SSH into container | `ddev ssh` |
+| Run composer | `ddev composer ...` |
+| Database export | `ddev export-db > dump.sql.gz` |
+| Database import | `ddev import-db < dump.sql.gz` |
+| View logs | `ddev logs` |
+| Restart | `ddev restart` |
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START patterns -->
+## Key Patterns
+- Use `ddev composer` instead of local composer
+- Custom commands in `.ddev/commands/` for project-specific tasks
+- Override services with `docker-compose.*.yaml` files
+- Use `ddev describe` to see URLs and credentials
+- Multi-version testing: change `php_version` in config.yaml
+<!-- AGENTS-GENERATED:END patterns -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Configuration Style
+- Keep `config.yaml` minimal, use overrides for complexity
+- Document custom commands with `## Description:` header
+- Use `#ddev-generated` comment for files DDEV manages
+- Pin addon versions for reproducibility
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR Checklist
+- [ ] `ddev start` works after changes
+- [ ] Custom commands have descriptions
+- [ ] No hardcoded paths or credentials
+- [ ] Works on macOS, Linux, and Windows (WSL2)
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START skill-reference -->
+## Skill Reference
+> For DDEV setup, TYPO3 multi-version testing, and custom commands:
+> **Invoke skill:** `typo3-ddev`
+<!-- AGENTS-GENERATED:END skill-reference -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/docker.md

@@ -0,0 +1,160 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+{{DOCKER_VERSION_LINE}}
+{{COMPOSE_VERSION_LINE}}
+{{REGISTRY_LINE}}
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START structure -->
+## Directory structure
+```
+docker/                      # or deploy/, .docker/, infrastructure/
+  Dockerfile                 → Main application image
+  Dockerfile.dev             → Development image (optional)
+  docker-compose.yml         → Local development stack
+  docker-compose.prod.yml    → Production overrides
+  .dockerignore              → Build context exclusions
+  entrypoint.sh              → Container entrypoint script
+  healthcheck.sh             → Health check script
+```
+<!-- AGENTS-GENERATED:END structure -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & run
+| Task | Command |
+|------|---------|
+| Build image | `docker build -t app .` |
+| Run container | `docker run -p 8080:80 app` |
+| Start stack | `docker compose up -d` |
+| View logs | `docker compose logs -f` |
+| Stop stack | `docker compose down` |
+| Rebuild | `docker compose up -d --build` |
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Dockerfile conventions
+- **Multi-stage builds**: Separate build and runtime stages
+- **Non-root user**: Run as non-root user in production
+- **Layer caching**: Order instructions from least to most frequently changing
+- **Specific versions**: Pin base image versions (e.g., `node:20-alpine`, not `node:latest`)
+- **COPY over ADD**: Prefer COPY unless extracting archives
+- **.dockerignore**: Exclude unnecessary files from build context
+
+### Naming conventions
+| Type | Convention | Example |
+|------|------------|---------|
+| Dockerfile | `Dockerfile` or `Dockerfile.<variant>` | `Dockerfile.dev` |
+| Compose file | `docker-compose.yml` or `compose.yml` | `docker-compose.prod.yml` |
+| Image tag | `<registry>/<name>:<version>` | `ghcr.io/org/app:1.2.3` |
+| Service name | lowercase with hyphens | `web-app`, `postgres-db` |
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START patterns -->
+## Common patterns
+
+### Multi-stage build
+```dockerfile
+# Build stage
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Runtime stage
+FROM node:20-alpine AS runtime
+WORKDIR /app
+RUN addgroup -g 1001 appgroup && adduser -u 1001 -G appgroup -s /bin/sh -D appuser
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+USER appuser
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+### Health check
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+```
+
+### Compose with profiles
+```yaml
+services:
+  app:
+    build: .
+    profiles: ["dev", "prod"]
+  debug:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    profiles: ["dev"]
+```
+<!-- AGENTS-GENERATED:END patterns -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- **No secrets in images**: Use runtime environment variables or secret mounts
+- **Non-root execution**: Always use USER directive in production
+- **Minimal base images**: Prefer Alpine or distroless images
+- **Scan images**: Use `docker scout`, `trivy`, or similar tools
+- **Pin versions**: Avoid `latest` tags for reproducibility
+- **Read-only filesystem**: Use `--read-only` when possible
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] Dockerfile builds successfully
+- [ ] Image runs without errors
+- [ ] Non-root user configured for production
+- [ ] .dockerignore excludes sensitive/unnecessary files
+- [ ] Health check configured
+- [ ] No secrets or credentials in image layers
+- [ ] Base image version pinned
+- [ ] Multi-stage build used where appropriate
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Docker docs: https://docs.docker.com
+- Dockerfile best practices: https://docs.docker.com/develop/develop-images/dockerfile_best-practices/
+- Compose specification: https://docs.docker.com/compose/compose-file/
+- Check existing Dockerfiles in this repo for patterns
+- Review root AGENTS.md for project-wide conventions
+<!-- AGENTS-GENERATED:END help -->
+
+<!-- AGENTS-GENERATED:START skill-reference -->
+## Skill Reference
+> For Dockerfile best practices, multi-stage builds, and compose patterns:
+> **Invoke skill:** `docker-development`
+<!-- AGENTS-GENERATED:END skill-reference -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/documentation.md

@@ -0,0 +1,98 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+- Documentation may use a static site generator (check for config files)
+- Preview locally before committing major changes
+- Check for broken links and formatting issues
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Building docs
+- Preview: check for `npm run docs`, `make docs`, or similar
+- Build: check for documentation build commands in root
+- Serve locally to verify rendering
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START structure -->
+## Documentation structure
+- `README.md` - Entry point, project overview
+- `getting-started/` - Installation and quick start guides
+- `guides/` - How-to guides and tutorials
+- `reference/` - API documentation, configuration reference
+- `architecture/` - Design documents, ADRs
+- `contributing/` - Contribution guidelines
+<!-- AGENTS-GENERATED:END structure -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- Use clear, concise language
+- Include code examples for technical concepts
+- Keep line length reasonable (~80-120 chars for readability)
+- Use consistent heading hierarchy (H1 for page title, H2 for sections)
+- Add alt text to images for accessibility
+- Use relative links for internal references
+- Keep code examples up-to-date with actual codebase
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START markdown -->
+## Markdown best practices
+- Use fenced code blocks with language hints: ```python
+- Use tables for structured data comparison
+- Use admonitions for warnings/notes (if supported)
+- Keep paragraphs focused on one idea
+- Use bullet points for lists, numbered lists for sequences
+<!-- AGENTS-GENERATED:END markdown -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Never include secrets, API keys, or credentials in examples
+- Use placeholder values: `your-api-key`, `example.com`
+- Review screenshots for sensitive information
+- Avoid documenting security vulnerabilities in detail
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] Documentation matches current code behavior
+- [ ] Code examples are tested and work
+- [ ] Links are valid (no 404s)
+- [ ] Images have alt text
+- [ ] Spelling and grammar checked
+- [ ] Formatting renders correctly
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check existing documentation for patterns
+- Review the style guide (if one exists)
+- Preview changes locally before committing
+- Check root AGENTS.md for project conventions
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}

package/skills/repo-bootstrap/assets/scoped/examples.md

@@ -0,0 +1,96 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+{{SCOPE_DESCRIPTION}}
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+{{SCOPE_FILE_MAP}}
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+{{SCOPE_GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+- Examples should be self-contained and runnable
+- Each example may have its own dependencies (check local README)
+- Examples should work with the current version of the main package
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Running examples
+- Check each example's README for specific instructions
+- Most examples: `cd example-name && follow README`
+- Some examples may require environment setup
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START organization -->
+## Example organization
+- One directory per example/use case
+- Each example has its own README explaining what it demonstrates
+- Keep examples focused on one concept or pattern
+- Name examples descriptively: `basic-usage/`, `advanced-config/`, `integration-with-x/`
+<!-- AGENTS-GENERATED:END organization -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- Examples should be educational and well-commented
+- Use realistic but simplified scenarios
+- Show best practices, not shortcuts
+- Include error handling to demonstrate proper patterns
+- Keep examples minimal - only what's needed to demonstrate the concept
+- Avoid complex setups that distract from the main point
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START documentation -->
+## Documentation requirements
+- Each example needs a README with:
+  - What this example demonstrates
+  - Prerequisites and setup steps
+  - How to run the example
+  - Expected output or behavior
+  - Links to relevant documentation
+<!-- AGENTS-GENERATED:END documentation -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Never include real API keys or credentials
+- Use environment variables for sensitive config: `export API_KEY=your-key`
+- Use sandbox/test environments when interacting with external services
+- Include warnings for examples that make real API calls
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] Example runs successfully
+- [ ] README is complete and accurate
+- [ ] No hardcoded credentials
+- [ ] Code demonstrates best practices
+- [ ] Comments explain non-obvious parts
+- [ ] Example works with current package version
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check similar examples for patterns
+- Ensure the example is self-contained
+- Test the example from scratch (fresh environment)
+- Check root AGENTS.md for project conventions
+<!-- AGENTS-GENERATED:END help -->
+
+## House Rules (project-specific)
+<!-- This section is NOT auto-generated - add your project-specific rules here -->
+{{HOUSE_RULES}}