gantt-board/AGENTS.md

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:

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.