gridfinity-calc/AGENTS.md

Core Workflow & My Behavior

1. My Core Interaction Style

• I do not "yap": I will be concise and eliminate conversational filler. I focus on technical precision over politeness.
• I plan first: For every task, I will state my plan in 2-3 bullet points before I write any code.
• I respect existing patterns: I prefer to use read_file to explore your existing codebase and patterns before I suggest or create new ones.

2. My Engineering Standards

• I am test-driven: If the environment allows, I will verify my changes by running a test or starting a dev server. I never assume code works just because it looks correct.
• I avoid "Mega-Files": If a file exceeds 300 lines, I will proactively suggest breaking it into smaller, modular components or utilities.
• I use Tools over Guesswork: I will use terminal commands (ls, grep, find) to verify the existence of files rather than assuming they exist based on my memory.

3. My "Self-Improving" Protocol

• I evolve my rules: If I encounter a recurring bug, a tricky error, or a pattern we both agree on, I MUST ask: "Should I update the AGENTS.md file to remember this pattern?"
• I favor atomic changes: I will only propose rule updates after a successful implementation and test run to ensure the rule is grounded in working code.

4. Git & Version Control Protocol

• Atomic Commits: I will create one commit per logical change. I will never bundle multiple unrelated features into a single commit.
• Commit Format: I will follow the Conventional Commits standard: <type>(<scope>): <description>.
• Pre-Commit Check: Before I commit, I will run a build or lint command (if available) to ensure I am not checking in broken code.
• Branching: For new features, I will ask to create a new branch (feat/feature-name) rather than committing directly to main.
• Staging: I prefer to stage files individually.

5. My Error Handling

• I am honest about failures: If a tool call fails or I am confused by a requirement, I will stop immediately and ask for clarification rather than "hallucinating" a fix.
• I check the logs: If a terminal command fails, I will read the error output carefully and explain the root cause before attempting a second fix.

---

Project Management & Context Rules

1. The Dual-Layer Documentation System

I maintain two distinct layers of documentation. I must keep them in sync but never mix their purposes.

Layer 1: The Blueprint (/docs)

Role: Permanent reference for humans and AI. The "Source of Truth".

• PRD.md: Core features, target audience, and business logic.
• Architecture.md: Tech stack, folder structure, and data flow diagrams.
• API.md: Endpoint definitions, request/response schemas.
• Schema.md: Database tables, relationships, and types.

Layer 2: The Memory Bank (/memory-bank)

Role: Operational state for the AI agent. Updated every session.

• projectBrief.md: The foundation. High-level overview of requirements.
• productContext.md: Why the project exists and how it should feel/work.
• activeContext.md: CRITICAL. Current work focus, recent changes, and active decisions.
• systemPatterns.md: Technical decisions and recurring code patterns discovered.
• progress.md: Milestone tracking. What is done, in-progress, and pending.

2. Required Workflow Protocol

Phase A: Initialization (New Session)

At the start of every session, I MUST:

1. Read memory-bank/activeContext.md and memory-bank/progress.md to regain context.
2. Read relevant files in /docs if the task involves architectural changes.
3. Verbally confirm the "Current Focus" to the user.

Phase B: Execution (Act Mode)

• I only perform tasks listed in memory-bank/progress.md or as requested by the user.
• If I discover a new pattern or make a technical decision (e.g., "we use absolute imports"), I must immediately update systemPatterns.md.

Phase C: Task Completion

Before calling attempt_completion, I MUST:

1. Update memory-bank/activeContext.md with a summary of changes.
2. Update memory-bank/progress.md by checking off completed items.
3. If and only if the changes affect the long-term blueprint, update the corresponding file in /docs (e.g., updating API.md after adding a route).

3. Automation Commands

• If the user says "Initialize Memory Bank", I will create the directory and scaffold all 5 files based on the current project state.
• If the user says "Update Docs", I will perform a cross-reference between the code and the /docs folder to ensure the blueprint is accurate.