Imported from gvillarroel/technology (AGENTS.md). Install upstream with npx skills add gvillarroel/technology. Copyright stays with the author.

AGENTS.md

Working Rules

• Always use English in every document, comment, and written artifact in this repository.
• Keep governed site data outside the repository. Do not introduce local structured-content roots such as data/ or src/data/.

Project References

Read the following documents when they are relevant to the task:

• .specs/adr/*.md: technical decision records.
• .specs/spikes/**/README.md: summaries of technical experiments, including conclusions, lessons learned, and references to related files.
• .specs/designs.md: preferred design and styling guidance.
• gs://limited-502918-cheap-gcs/technology/site.json: private route registry, presentation configuration, and datasets.
• Original GitHub repositories declared in the remote catalog: preferred sources for repository-backed ADRs, documentation, and skills.
• Record new durable technical or workflow decisions as ADRs under .specs/adr/*.md.

Workflow

• Work locally first and keep the online version updated through pushes.
• Use a single shared local web session for this repository whenever a live service is needed. Prefer reusing the existing session instead of starting another one on a different port.
• The default shared development server command is npm run dev -- --host 0.0.0.0 --port 4321. Check whether http://localhost:4321/ is already responding before starting a new instance.
• If a shared session is already running, use that URL for review, Playwright checks, and screenshots instead of launching an additional server.
• Keep Markdown route parity for every page under src/pages: each .astro page must have a matching .md.ts route, and commits should pass npm run check:markdown-pages.
• After every visual or UI-related modification, run Playwright-based verification when feasible.
• After each relevant change, capture one focused screenshot of the most relevant or changed section rather than the entire page, and share it in the chat so visual feedback can be reviewed iteratively.
• After each relevant web change, also share the URL where the updated page can be reviewed, whether that is a local preview URL or the deployed URL.
• Use the screenshot review loop as a default part of the implementation workflow for front-end changes.

Repository organization and documentation

• Keep README.md as an overview: purpose, critical boundaries, first useful action, and links into docs/README.md.
• Put detailed procedures and reference material in docs/; update its index with every addition or move.
• Follow the repository guide for file placement, validation, and data boundaries.
• Preserve existing canonical specs, ADRs, skill bundles, and evidence paths; do not reorganize sealed or generated data as documentation.
• Preserve prior work, stage explicit paths, and verify links, relevant checks, and the diff before an authorized push.
• Build tools must not delete authored documentation. Keep transient output and credentials outside tracked source.