Signed-off-by: Max <ai-agent@topdoglabs.com>

AGENTS.md

@@ -0,0 +1,76 @@
+# AGENTS.md
+
+Guidance for AI/code agents working in this repository.
+
+## Project Snapshot
+
+- App: Gantt Board (`Next.js` + TypeScript)
+- Backend: API routes in `src/app/api/*` with Supabase-backed persistence
+- Clients:
+  - Web UI (React/Next)
+  - Shell CLI scripts in `scripts/`
+
+## Core Architecture Rules
+
+1. API/server code is the single source of truth for business logic.
+2. CLI scripts are passthrough clients to API endpoints.
+3. CLI scripts must not implement domain/business logic.
+4. CLI scripts must not perform direct DB/Supabase REST access.
+5. If CLI needs missing behavior, add it to API first, then call it from CLI.
+
+Reference docs:
+
+- `scripts/README.md`
+- `CLI_STANDARD.md`
+- `docs/API_CLI_PASSTHROUGH_PATTERN.md`
+
+## Important Domain Note
+
+Current sprint selection/date semantics are centralized in server logic:
+
+- `src/lib/server/sprintSelection.ts`
+
+Do not duplicate this logic in CLI or UI scripts.
+
+## Testing Requirements
+
+For API/CLI refactors and behavior changes, tests are required.
+
+Minimum checks:
+
+```bash
+npm run test:refactor
+```
+
+This must stay green before considering work complete.
+
+When relevant, also run other project checks (build/lint/test) and report failures clearly.
+
+## Documentation Sync Policy (Required)
+
+When behavior, commands, architecture, or contracts change, update docs in the same change.
+
+At minimum, review and update as needed:
+
+1. `README.md` (root project behavior + CLI section)
+2. `scripts/README.md` (actual command usage and env vars)
+3. `CLI_STANDARD.md` (integration standard)
+4. `docs/API_CLI_PASSTHROUGH_PATTERN.md` (pattern/rules)
+
+If a refactor lands without doc updates, the task is incomplete.
+
+## Refactor Completion Checklist
+
+- [ ] Business logic lives in API/server only
+- [ ] CLI only calls API (`scripts/lib/api_client.sh` path)
+- [ ] No direct DB references in `scripts/`
+- [ ] `npm run test:refactor` passes
+- [ ] Docs updated to match shipped behavior
+- [ ] Any deprecated usage removed or marked clearly
+
+## Implementation Preferences
+
+- Prefer minimal, safe changes over large rewrites.
+- Preserve existing file conventions and script UX.
+- Keep backward-compatible wrappers only when needed; document them.
+- If you find stale docs/examples, fix them as part of the same work.