project-conventions

Project Conventions Skill — Respect Existing Code

Purpose

When working on an EXISTING project (not greenfield), agents MUST discover and respect the established conventions. This skill provides the discovery protocol and rules for matching existing patterns.

Step 1: Convention Discovery (MANDATORY — Before Writing Any Code)

Before touching any file in an existing project, run this discovery:

1.1 Architecture Discovery

1. Read project root files: package.json, composer.json, pubspec.yaml, Cargo.toml, etc.
2. Identify ALL frameworks and their versions
3. Map the directory structure:
   - Where are controllers? (app/Http/Controllers, src/controllers, lib/controllers)
   - Where are models? (app/Models, src/models, lib/models)
   - Where are views/pages? (resources/views, src/pages, lib/screens)
   - Where are services? (app/Services, src/services, lib/services)
   - Where are API routes? (routes/api.php, src/routes/, pages/api/)
   - Where are tests? (tests/, __tests__/, test/, spec/)
4. Identify the project's entry point(s)

1.2 Query/Request Pattern Discovery

For Backend (Laravel, NestJS, Express, Django, etc.):
- How does the frontend call the backend? (REST, GraphQL, tRPC, gRPC)
- What HTTP client does the frontend use? (axios, fetch, http, dio)
- How are API endpoints structured? (/api/v1/resource, /resource, /graphql)
- How is authentication handled? (Bearer token, session, cookie, API key)
- How are errors returned? ({error: "msg"}, {message: "msg"}, Problem Details)
- How is pagination handled? (cursor, offset, relay-style)

For Frontend (Flutter, React, Vue, etc.):
- How does it fetch data? (Riverpod + dio, Redux + axios, hooks + fetch, BLoC + http)
- How is state managed? (Provider, BLoC, Riverpod, Redux, Vuex, Pinia, getX)
- How are forms handled? (Form widgets, react-hook-form, vee-validate)
- How are routes defined? (named routes, GoRouter, React Router, Vue Router)
- How are API calls structured? (repository pattern, service layer, direct calls)