agents in

AGENTS.md

@@ -0,0 +1,68 @@
+# Agent Operating Guide
+
+Use this file as the first entrypoint for work in this repository.
+
+If [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) exists and contains filled-in defaults, read it immediately after this file and treat it as the source of preloaded project preferences unless the destination repository provides stronger instructions.
+
+## Default Behavior
+
+- Inspect the repository before making assumptions.
+- Prefer implementing and verifying work over giving abstract advice unless the user explicitly asks for planning only.
+- Read only the skill files needed for the current task.
+- Reuse existing project patterns, naming, architecture, and conventions.
+- Test or validate changes when feasible, then summarize outcomes and any remaining risks.
+- Update or create documentation when the change affects usage, onboarding, behavior, or developer workflow.
+- If repository-specific instructions conflict with this suite, follow the repository-specific instructions.
+
+## How To Load Skills
+
+1. Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in for this deployment.
+2. Read [SKILLS.md](./SKILLS.md).
+3. Identify the task category and open the matching hub file.
+4. Open only the specialized skill files relevant to the request.
+5. Combine skills when the task spans multiple areas.
+6. Avoid loading unrelated skills just because they exist.
+
+## Context Economy Rules
+
+- Default to reading one hub and two to four specialized skills for a normal task.
+- Add more skills only when they materially change the approach, output, or quality bar.
+- Prefer depth in the relevant skills over shallow loading across many categories.
+- If two skills overlap heavily, choose the one that best matches the main risk or deliverable.
+- Re-open the index when the task shifts, but do not reload the entire library reflexively.
+- Treat the deployment profile as the early context layer and avoid re-reading it unless the task changes the relevant preference area.
+
+## Instruction Precedence
+
+Apply guidance in this order:
+
+1. Destination repository instructions
+2. [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md)
+3. Generic routing and skill guidance from this suite
+
+## Routing Table
+
+| Task type | Start here |
+| --- | --- |
+| Feature work, refactors, reviews, tests, backend, frontend | [hubs/software-development.md](./hubs/software-development.md) |
+| Failing tests, bugs, incident-style analysis, root-cause work | [hubs/debugging.md](./hubs/debugging.md) |
+| Technical docs, onboarding, release notes, change communication | [hubs/documentation.md](./hubs/documentation.md) |
+| UX evaluation, UI polish, interaction quality, content design | [hubs/ui-ux.md](./hubs/ui-ux.md) |
+| Product copy, launch messaging, marketing content | [hubs/marketing.md](./hubs/marketing.md) |
+| Ideation, option generation, structured brainstorming | [hubs/brainstorming.md](./hubs/brainstorming.md) |
+
+## Combination Rules
+
+- For new features, combine implementation + test strategy + relevant docs.
+- For UI work, combine frontend implementation + UX review + product copy when text matters.
+- For broken behavior, combine bug triage + debugging workflow + change summary when a fix lands.
+- For launch or release tasks, combine technical docs or release notes with messaging or marketing skills as needed.
+- For high-risk changes, add security review, observability, or performance optimization as appropriate.
+- For long-lived system changes, add architecture and system design, dependency lifecycle, or database migration planning when relevant.
+
+## Output Expectations
+
+- Deliver concrete work products, not just observations.
+- State key assumptions when the repository does not answer them.
+- Call out blockers, tradeoffs, risks, and unverified areas clearly.
+- Keep explanations concise and action-oriented.