# 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.