Skip to content

AGENTS.md

Latest commit

 

History

History
36 lines (30 loc) · 2.91 KB

AGENTS.md

File metadata and controls

36 lines (30 loc) · 2.91 KB

Repository Guidelines

Project Structure & Module Organization

  • shoulda/ contains the Python agent package; extend modules under agents/ for new capabilities.
  • frontend/ houses the Next.js client; use src/components for shared UI, hooks/ for client state, and store static assets in public/.
  • infra/ holds the AWS CDK app (lib/ for stacks, lambda/ for runtime code) with helper scripts under infra/scripts/.
  • docs/ captures architecture notes; review docs/AGENT_CORE.md before touching orchestration logic, and keep new design write-ups here.
  • scripts/ provides deployment and Cognito utilities—mirror their structure if you add agent automation.

Build, Test, and Development Commands

  • uv sync --dev installs backend dependencies for the agent package.
  • uv run pytest, uv run ruff check ., and uv run ruff format . cover backend tests, linting, and formatting.
  • cd frontend && npm install once per laptop; npm run dev, npm test, and npm run lint drive local Next.js work.
  • cd infra && npm install; npm run build compiles TypeScript, while npm run cdk -- deploy applies infrastructure (use a sandbox AWS profile).

Coding Style & Naming Conventions

  • Python follows Ruff (line-length=100, double quotes, spaces); keep modules/functions snake_case, classes PascalCase, and annotate public callables.
  • Frontend code is TypeScript-first with ESLint; keep React components and hooks in PascalCase and colocate styles/tests when practical.
  • CDK constructs in infra/lib stay PascalCase; configuration belongs in context files or environment variables, not hard-coded constants.

Testing Guidelines

  • Add test or test case only if it adds significant value.
  • Store backend tests under tests/, naming files test_<module>.py; mock FRED/Yahoo/AWS integrations so pytest stays offline.
  • Frontend uses Jest + Testing Library; create *.test.tsx close to the component or under __tests__/.
  • Infrastructure tests live in infra/test/; run npm test after TypeScript changes and before deploying stacks.

Playwright Testing

  • Use the Playwright MCP runner to drive end-to-end UI checks while the Next.js dev server is running on http://localhost:3000.
  • The shared browser profile retains Amplify localStorage tokens; existing demo sessions will skip the login screen.
  • Use smaller viewport size to reduce screenshot size.

Commit & Pull Request Guidelines

  • Commits use short, imperative summaries (add aws s3 and cloudfront); split unrelated changes and include context in the body when useful.
  • Reference tickets or docs, tag collaborators with Co-authored-by if applicable, and keep branches current with main.
  • PRs must describe motivation, local verification (commands run, screenshots for UI), and deployment impact; link to any related documentation updates.
  • Ensure backend tests, frontend lint/tests, and npm run build for infra all pass before requesting review.