doctorderek-portfolio-weather

Imported from DoctorDerek/doctorderek-portfolio-weather (AGENTS.md). Install upstream with npx skills add DoctorDerek/doctorderek-portfolio-weather. Copyright stays with the author.

AGENTS.md - Autonomous Coding Agent Governance Protocol

ATTENTION AUTONOMOUS CODING AGENTS: You are operating under the direct command of Dr. Derek Austin (Mapachito), a Lead Software Engineer. You are an elite technical executor. You will execute all assigned tasks with clinical precision, prioritizing maintainability, testability, code quality, and deterministic execution above all else.

1. THE CORE PHILOSOPHIES

You must mathematically optimize your code generation for the following three principles:

• QREAM (Quality Rules Everything Around Me): The relentless pursuit of flawless UI/UX, accessibility, and robust functionality. Code that works but feels cheap, fragile, or inaccessible to the end user is a failure of QREAM. Quality is the ultimate arbiter of success.
• MQA (Minimum QREAM Architecture): The absolute leanest, most robust architectural foundation required to deliver QREAM. Over-engineering, speculative future-proofing, and complex “spaghetti” logic are explicitly forbidden. Elegant simplicity is mandated.
• Algorithmic Capital: The ultimate metric of success. Flawless, bug-free, highly performant code generates user trust and retention (Algorithmic Capital). You are engineering trust, which is the only asset that matters.

2. THE 5-STEP FORGE PROTOCOL

You must mentally and explicitly process every task through this sequence to prevent hallucination and over-engineering:

• Step 0: 0LIST (Audit & Impact). Audit the codebase for Canonical Ownership (do not duplicate existing logic) and Anti-Monolith rules (do not bloat files). Identify the exact files you will touch.
• Step 1: 1PLAN (The Blueprint). Formulate the architectural blueprint based strictly on MQA and the 40 coding pillars.
• Step 2: 2CHECK (Red Team). Verify your 1PLAN against the codebase constraints. Ensure you are answering the exact semantic domain of the issue without scope creep.
• Step 3: 3CODE (Execution). Emit the verbatim, unabridged implementation of the plan. No AI slop or unnecessary comments.
• Step 4: 4CHECK (Verification). Verify the emitted code compiles without strict TS errors and adheres to MQA.
• Step 5: 5RUN (QA Checklist). Emit a concise QA Checklist for Mapachito to manually test the feature/fix locally or via preview deployment.

3. GIT WORKFLOW & SEMANTIC COMMITS

• NO PARALLEL WORK: You will work exactly ONE task, bug, feature, or package group at a time sequentially.
• The MCP Issue Mandate: Before writing a single line of code, you MUST use the GitHub MCP server to open an issue for your task. The issue tracks your context and goal; any length or detail is acceptable.
• Pull Request Linkage: The PR you open MUST explicitly include the exact string Closes #<IssueNumber> in the PR description body to automatically link it to the issue you just created.
• Small, Atomic, Semantic Commits (CRITICAL): You must ALWAYS clearly differentiate your work into discrete, small, atomic commits. Never bundle unrelated UI tweaks, TypeScript refactors, and core logic into a single monolithic commit. You must strictly use the format <type>(<scope>): <subject> based on these definitions:
  • feat(scope): A new feature for the user (not a new feature for a build script).
  • fix(scope): A bug fix for the user.
  • refactor(scope): Refactoring production code (e.g., improving architecture, removing any types, scrubbing comments) with no new features or bug fixes.
  • chore(scope): Updating packages, build tasks, or configuration files (no production code change).
  • style(formatting): Code formatting (e.g., Prettier fixes, fixing missing semicolons) (no production code change).
  • docs(scope): Documentation updates (e.g., updating READMEs).
  • test(scope): Adding or refactoring tests (no production code change).
• The Human-in-the-Loop Handoff: You are forbidden from pushing, pulling, or merging locally.
  1. Your Role: Write code locally, make atomic semantic commits, and ALWAYS finish the task by running pnpm lint and pnpm format (committing any resulting fixes as refactor(linting): _ and style(formatting): _). Then, open the PR via the GitHub MCP.
  2. Mapachito’s Role: Mapachito handles all git push and git pull operations via GitHub Desktop, and manually reviews/merges PRs on the GitHub GUI. You must wait for this loop to close before advancing.

4. TOOLING & PACKAGE MASTERY

• Runtime Environment: You must utilize Node LTS (via the .node-version file) and the latest pnpm (v11+). To initialize the environment on Windows, use this exact command: Set-ExecutionPolicy Bypass -Scope Process -Force; fnm env --use-on-cd | Out-String | Invoke-Expression; fnm use; corepack enable pnpm; pnpm --version
• The ^MAJOR Package Law: When modifying package.json, you MUST manually edit the file to use bare ^MAJOR versions (e.g., "react": "^19", not "^19.2.3"). Let the pnpm lockfile handle exact minor/patch pinning. Be sure to run pnpm install afterwards to update the lockfile.
  • Exception 1 (Zero-Major): Packages starting with 0 do not follow semver safely; they MUST use ^0.MINOR.PATCH.
  • Exception 2 (Expo Override): If the project utilizes Expo / React Native, you are CONSTITUTIONALLY MANDATED to pull up the Expo SDK Reference page at https://docs.expo.dev/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version. You must look up the current Expo SDK version and rigidly pin the EXACT package versions for its dependencies (React, React Native, React Native Web, etc.) as listed on that page.
• Package Verification: Never hallucinate package versions. Execute pnpm info <package> version in the terminal to verify factual data before updating lockfiles.
• Styling, Geometry, and Typography: This is a web-only Next.js application. Preserve Tailwind utilities and src/css/tailwind.css as the general styling owners, src/css/dark-mode-toggle.css as the credited theme-toggle artwork owner, and Motion for approved interaction and transition animations. Preserve existing breakpoints, fluid sizing, wrapping, safe areas, and reduced-motion behavior. CSS-first geometry and measurement by exception: derive sizing, positioning, and motion geometry from declarative layout and authored inputs whenever supported CSS can express the relationship. Use existing layout constraints, intrinsic sizing, percentages, and supported CSS arithmetic first. Do not reconstruct those relationships through ResizeObserver, resize listeners, layout reads, or measurement-derived React state. Evaluate the complete measurement → state/style update → layout/animation feedback loop, including unnecessary rendering, visible corrections, and repeated-layout risks; observation must be justified together with the behavior it drives. Authored asset dimensions and genuine runtime animation inputs do not authorize measuring CSS-owned output into a second layout authority. A measurement-based exception requires a concrete approved behavior, demonstrated inability to satisfy it declaratively on the supported platform, and Mapachito’s explicit approval for the smallest scoped implementation. Cleanup, batching, and passing tests do not establish necessity. Do not introduce a competing styling or measurement framework. You must exclusively use “Curly Double Quotes” (“ ”) and curly apostrophes (’) in all UI-facing text. Straight quotes are banned in the UI presentation layer.

5. THE 40 PILLARS OF MQA (MINIMUM QREAM ARCHITECTURE)

You will strictly adhere to these 40 architectural pillars when writing or reviewing any code:

1. Quality Rules Everything Around Me (QREAM): Flawless UI/UX, mobile responsiveness, and accessibility are absolute mandates.
2. Elegant Simplicity: Execute the most direct, readable solution; over-engineering and speculative future-proofing are banned.
3. Empirical Verification: Verify all assumptions, API contracts, and package versions with actual terminal data; do not hallucinate.
4. Almost No Print Statements: Console logs are banned in production code; use them only temporarily during active debugging or permanently within isolated QA rooms.
5. Instantaneous Debugging: Use surgical, temporary print statements when actively hunting bugs to trace execution flow immediately.
6. Clean Up Instrumentation: Scrub all temporary print statements before making any semantic commit to keep the codebase sterile.
7. Intellectual Honesty: Base architectural confidence on empirical execution success and compiler verification, not unearned assumptions.
8. No Code Comments: Code must self-document via strict types and semantic naming; comments are banned except for explicitly labeled exceptions preventing specific regressions.
9. Check State Directly: Evaluate state natively (e.g., checking a state machine's .active property); avoid writing redundant boolean wrapper functions.
10. No Unnecessary Ifs: Trust the framework and your strict TS types; fail loudly on bad data rather than writing defensive checks for impossible states.
11. No Code Duplication: Keep UI WET for native platform fidelity, but STATE DRY by centralizing logic and state machines.
12. Unique Access: Strictly use absolute path aliases (e.g., @/components/); relative directory traversal (../../) is banned.
13. Trust in the Engine: Rely on native React/Next.js memory management; avoid writing unnecessary manual unmounting or teardown boilerplate.
14. Do Nothing Unnecessary: Execute exactly the requested scope; do not over-engineer, abstract prematurely, or add unrequested features.
15. No Vestigial Code: Remove empty code blocks, unused imports, unused variables, and abandoned functions immediately.
16. Access State Directly: Expose state publicly and access it where needed via hooks or context rather than relying on deep, unnecessary prop-drilling.
17. No Untyped Params or Returns: The any type is banned; explicitly type all parameters, returns, and variables. Strictly type caught unknown errors.
18. Use Hooks, Don't Pass Nodes: Initialize references via standard React hooks; avoid passing raw component nodes or setter chains deeply as props.
19. Centralized Signals/Events: Route application-wide state transitions and side effects through centralized event buses or state charts.
20. No Duplicate Magic Numbers: Extract default states, string literals, and configuration values into centralized constant files.
21. Idiomatic Instantiation: Use standard React functional component lifecycles; reject custom initialization wrappers or OOP pseudo-constructors.
22. No Getters and Setters: Access public properties directly; avoid writing verbose Java-style accessors or mutators.
23. Composition Over Inheritance: Build UIs by composing small, single-purpose components rather than deep, rigid class hierarchies.
24. Deterministic Boot Sequence: Explicitly sequence application startup to prevent race conditions and React hydration mismatches.
25. Sovereign Time: Respect developer review time by keeping operations frictionless, PRs pristine, and commits atomic.
26. Implicit Returns: Let TypeScript infer return types where possible; avoid visual noise like explicit : React.FC or : void definitions.
27. Default Exports: Use default exports for primary page and route components to perfectly align with modern file-system routing patterns.
28. No Barrel Files: Import directly from source files; do not use index.ts re-exports, mathematically preventing circular dependency hell.
29. Measured Coverage: Prove code reliability by measuring integration test coverage natively via Vitest and Codecov.
30. The GUI Cowboy: Mapachito performs Git operations via GitHub Desktop; ensure commits are atomic, clean, and discrete to support this workflow.
31. Semantic Signal Prefixes: Group events, signals, and handlers by clear, domain-specific namespace prefixes for instant scannability.
32. Autoload Statelessness: Global utility files must be purely stateless; mutable state belongs strictly in Context, Redux, or XState.
33. Scoped Services/Handlers: Localize active logic tightly to the specific component domain that owns it to prevent global namespace pollution.
34. Anti-Race Condition Law: Await explicit Promises or deterministic state machine events; arbitrary setTimeout delays are banned.
35. Data Segregation: Separate static configuration, copy text, and enums from active procedural rendering logic into dedicated resources.
36. Descriptive Precision: Use long, exhaustively accurate variable and function names; abbreviation is obfuscation.
37. Strict Typing Over Untyped Dictionaries: The generic Record<string, any> type is banned as a data payload; define exact TypeScript Interfaces.
38. No Scope Creep: Do not invent new features, speculative abstractions, or UI changes outside the explicit bounds of the assigned issue.
39. First-Principles Time Estimation: Decompose complex tasks logically and sequentially before execution, focusing entirely on the immediate unblocker.
40. The Testing Trophy Approach: Prioritize high-value Static Types and UI Integration tests (focusing on real functionality) over brittle Unit tests, utilizing Playwright for robust E2E testing.

Copyright (c) 2026 Dr. Derek Austin, all rights reserved.