# AGENTS.md This repository uses @creo-team/wisdom for shared AI engineering instructions. Active profile: **package-first** — For repositories whose code may become npm packages. Emphasizes stable boundaries and public API discipline. ## Source of truth AGENTS.md is the canonical shared instruction file for AI coding agents. Tool-specific files adapt these rules for Claude, Cursor, Codex, Gemini, GitHub Copilot, and future agents. Every standard ships for every agent: when you add or change a rule, skill, prompt, memory policy, or specialist agent, deliver it for all supported agents in the same change — never for one tool only. Same intent, each tool's native format. See docs/ai/agent-standards.md. Local repo-specific instructions may live in .wisdom/overlays/. ## Default workflow For non-trivial work: 1. Confirm understanding: restate the ask as a user story and name acceptance criteria before building (see docs/ai/requirements.md). 2. Inspect the relevant files. 3. Identify existing patterns. 4. Propose a concise plan. 5. Implement the smallest safe diff. 6. Add reasonable tests. 7. Run relevant checks. 8. Summarize changed files, validation, and risks. Do not invent architecture when the repository already has a clear pattern. ## Communication Communicate leanly — concise by default, terse for machine-facing and agent-to-agent paths, clear and complete for humans; no filler. Reference instead of repeating; say it once. See docs/ai/token-economy.md. Treat colors, copy, and small tweaks as suggested implementation, not blocking requirements. ## Resolving reported issues When working through a batch of reported issues (feedback, QA notes, bug tickets), follow docs/ai/reported-issues.md: triage before touching anything, surface clashes and ambiguity instead of guessing, and pull reversals of prior decisions rather than steamrolling them. Never write to an issue or PR thread, self-merge, or edit a locked regression test without explicit human approval. ## Engineering standard Code should be boring, modular, testable, durable, stable, and easy to change. Prefer: - readable code over clever code - explicit names over vague names - flat code with early returns over nested conditionals - small functions over large procedural blobs - stable contracts over leaky implementation details - composition over inheritance unless inheritance is already the repo pattern - package-ready boundaries for reusable code - validation at external boundaries - side effects isolated near app and infrastructure edges - minimal dependencies - incremental changes Avoid: - nesting more than one level deep before refactoring - broad rewrites - speculative abstractions - hidden global state - tight coupling - non-obvious control flow - unvalidated external input - magic values; every literal traces back to an enum, constant, or config - empty catch blocks; log, rethrow, or document why an error is ignored - bare console statements in application code; use structured logging - logging secrets or sensitive data - changing public APIs without calling it out - tests that only assert implementation details - adding comments to explain confusing code before first trying to make the code intuitive ## Readability rule If code is difficult to follow: 1. improve names 2. simplify control flow 3. split large functions 4. introduce stronger types 5. separate pure logic from side effects 6. isolate framework and platform-specific code 7. only add comments if complexity is inherent Comments should explain why, not what. Do not write narration comments or section banners. ## Naming rule Names should reveal meaning. Good names should tell the reader: - what the value represents - whether it is raw, parsed, validated, normalized, cached, persisted, or derived - what unit it uses - whether the function has side effects - whether the value is public, private, internal, temporary, or external Name functions for what they do in the domain. Prefer specific domain verbs (get, create, list, update, remove, send) over vague transport verbs (fetch, post) when a clearer word fits. Avoid lazy names: - data - stuff - item - obj - util - helper - manager - handler when a more specific domain name exists - result when the result has a domain meaning - temp unless the temporary nature matters Acceptable generic names: - id - url - path - input - output - error - event - payload - request - response ## Type and module rule - TypeScript only in application code; strict mode enabled. - No `any`; prefer `unknown` and narrow with type guards. - Keep type definitions in dedicated `types.ts` files, not scattered across implementation. - Prefer named imports and named exports; avoid wildcard imports. - Framework-convention files (Next.js page, layout, route, sitemap, robots) may use default exports. - Use `null` for intentionally empty values and `undefined` for "not provided". ## Function design rule Prefer functions that: - do one meaningful thing - are easy to test - have clear inputs and outputs - avoid hidden dependencies - avoid hidden mutation - isolate side effects - return useful typed results - keep error handling explicit Avoid: - giant procedural blobs - boolean flag soup - functions that validate, transform, persist, log, notify, and format all at once - deep mutation - temporal coupling - hidden singleton state - functions that require a network, database, filesystem, or clock just to test simple logic ## Layering rule Where the repository uses a layered server architecture, keep the layering unidirectional: - Routes and actions handle HTTP concerns: auth check first, then input validation, then a service call, then response shaping. - Services hold business logic and orchestration. They call stores and external clients. - Stores are pure data access. They contain no business rules and no cross-domain store calls. Validate inbound data at the boundary (for example with a schema), and check `response.ok` before reading a fetch body. Apply timeouts to outbound calls. ## Testing rule Testing should provide confidence proportional to risk. Prefer: - focused unit tests for pure logic - integration tests for module boundaries - contract tests for exported APIs - smoke tests for critical wiring - regression tests for bugs Avoid: - snapshot spam - testing private implementation details - testing CSS class names unless they encode behavior - mocking everything by default - huge test matrices without risk justification - brittle tests that block refactoring - deleting tests to make changes pass If code is hard to test, improve the design before writing awkward tests. ## Package boundary rule Assume reusable modules may become npm packages later. Reusable code should: - avoid app-specific imports - avoid framework coupling unless explicitly package-scoped - expose small public APIs - keep internal implementation private - use dependency injection at volatile boundaries - avoid reading process.env directly outside config modules - avoid importing from app folders - define clear input and output contracts - preserve semver discipline once exported ## Extensibility rule Good extensibility is stable boundaries, not premature abstraction. Prefer: - narrow interfaces - simple public APIs - replaceable adapters - explicit contracts - dependency injection at volatile boundaries - additive changes - composition Avoid: - abstract classes with one implementation - plugin systems before plugins exist - generic factories everywhere - config-driven everything - clever type gymnastics - architecture-astronaut indirection ## Configuration rule Classify configuration as: 1. static committed config 2. runtime environment variable 3. secret 4. public client config 5. generated build metadata 6. user/admin-managed setting Use committed config for non-secret, stable, reviewable values. Use env vars for environment-specific runtime values. Use secrets for sensitive values. ## Secret rule Never commit, print, log, document, or memorize secrets. HALT if a secret is pasted into the chat, a prompt, or a file: stop, warn that it is now exposed, do not use or echo it, and tell the user to rotate it. Route secrets through a placeholder file the user fills locally, a session env var you reference by name, or a secrets manager — never chat, code, commits, or logs. Push back on insecure patterns instead of complying. See docs/ai/guardrails.md. Secrets include: - API keys - tokens - private keys - OAuth client secrets - database credentials - webhook signing secrets - cloud credentials GitHub repository or environment secrets should be treated as the CI/CD source of truth for workflow-needed secrets. Deployment platforms should receive secrets through audited workflows rather than hand-editing. Prefer OIDC or short-lived credentials when supported. ## Agent memory policy Agents may remember engineering preferences. Agents must not remember: - secrets - tokens - credentials - private keys - .env values - customer data - production incident details - proprietary client data unless explicitly approved Repo docs, ADRs, tests, and config schemas are the source of truth. Agent memory is never the source of truth. ## Commit and release rule - Use conventional commits (`type(scope): summary`); see docs/ai/git-workflow.md for the full type set. - Use bare semver everywhere — `package.json` version, git tag, release name, and any displayed version — with no `v` prefix (`1.4.0`, never `v1.4.0`). See docs/ai/git-workflow.md. - Bump the version with the change: in a published project (an npm/TS package or released app), move `package.json` `version` in the same commit that lands a shippable feature, fix, or breaking change (patch/minor/major per semver) so release tooling never re-tags or ships under a stale version. See docs/ai/git-workflow.md. - Practice trunk-based development: keep `main` always deployable, branches short-lived, changes small and atomic, and gate unreleased work behind feature flags. See docs/ai/git-workflow.md. - Single source of truth: every fact (config, copy, contracts, constants, types) is defined once and imported or linked — never duplicated. Drift is a bug. ## Completion report When finished, report: - what changed - why it changed - tests/checks run - risks - follow-up work # Agent Instructions — What Is DevOps Educational single-page site explaining DevOps principles, practices, culture, and recommended tools. Next.js 16 + React 19 + Tailwind CSS 4 + TypeScript. Dark aesthetic inspired by cursor.com. Built by Creo Design. Conventions live in exactly one place each — read them there instead of a restatement here: | Area | Document | |------|----------| | Repo conventions, design tokens, page map, trust rules, verification | [CLAUDE.md](CLAUDE.md) | | Generic engineering standards (style, testing, security, logging, …) | [docs/ai/](docs/ai/) via @creo-team/wisdom | | Cursor file-scoped rules | [.cursor/rules/](.cursor/rules/) | | DevOps & security principles for AI agents | [DEVOPS.md](DEVOPS.md) | Design token values are defined once in [app/globals.css](app/globals.css); components consume them as Tailwind utilities (`bg-canvas`, `text-ink`, `border-line-subtle`, …) — never raw hex. Version bumps are automated by the husky post-commit hook — never bump `package.json` manually. Verification commands: see CLAUDE.md.