SaaS-PDF/.github/copilot-instructions.md

Copilot Workspace Instructions

Purpose

• Help Copilot-style agents and contributors be productive and safe in this repository.
• Surface where to find authoritative docs and which conventions to follow.

Principles

• Link, don't embed: prefer linking to existing docs in docs/, CONTRIBUTING.md, or README.md rather than duplicating content.
• Minimize blast radius: make minimal, focused changes and explain rationale in PRs.
• Ask clarifying questions before large or ambiguous changes.

What the agent is allowed to do

• Suggest edits, create focused patches, and propose new files following repo style.
• Use apply_patch for file edits; create new files only when necessary.
• Run or suggest commands to run tests locally, but do not push or merge without human approval.

Conventions & expectations

• Follow existing code style and directory boundaries (backend/ for Flask/Python, frontend/ for Vite/TypeScript).
• When changing behavior, run tests and list the commands to reproduce the failure/fix.
• Keep PRs small and target a single logical change.

Key files & links (authoritative sources)

• README: README.md
• Contribution & tests: CONTRIBUTING.md
• Docker & run commands: docs/Docker-Commands-Guide.md
• Backend entry & requirements: backend/requirements.txt, backend/Dockerfile
• Frontend scripts: frontend/package.json, frontend/Dockerfile
• Compose files: docker-compose.yml, docker-compose.prod.yml
• Deployment scripts: scripts/deploy.sh

Common build & test commands

• Backend tests (project root):

cd backend && python -m pytest tests/ -q

• Frontend dev & tests:

cd frontend && npm install
cd frontend && npm run dev
cd frontend && npx vitest run

• Dev compose (full stack):

docker compose up --build

• Prod deploy (refer to scripts/deploy.sh):

./scripts/deploy.sh

Anti-patterns (avoid)

• Don't invent architectural decisions or rewrite large areas without explicit approval.
• Don't add secrets, large binary files, or unrelated formatting changes.
• Don't run destructive commands or modify CI/CD configuration without coordination.

Agent prompts & examples

• "Create a small Flask route in backend/app/routes that returns health JSON and add a unit test."
• "Refactor the image compression service to extract a helper; update callers and tests."
• "List the exact commands I should run to reproduce the failing tests for backend/tests/test_pdf_service.py."

Suggested follow-ups (agent customizations)

• create-agent:backend — focused on Python/Flask edits, runs pytest, and knows backend/ structure.
• create-agent:frontend — focused on Vite/TypeScript, runs vitest, and uses npm scripts.
• create-agent:ci — analyzes docker-compose.yml and scripts/deploy.sh, suggests CI checks and smoke tests.

If you want, I can:

• Open a draft PR with this file, or
• Expand the file with more precise command snippets and per-service README links.

---

Generated by a workspace bootstrap; iterate as needed.