# AGENT.md ## Purpose - This file defines repository-specific instructions for coding agents. - Scope is the full repo unless a deeper `AGENT.md` overrides it. - Use RTK to reduce token usage, avoid repeated context transfer, and preserve repository knowledge across sessions. --- # ✅ RTK-FIRST RULES (STRICT) Always prefer RTK commands for repository inspection, navigation, and code understanding. ## Command Rewrite Rules Prefer: ```bash git status -> rtk git status git diff -> rtk git diff git log -> rtk git log ls -> rtk ls tree -> rtk ls cat -> rtk read grep -> rtk grep rg -> rtk grep find -> rtk find ``` Avoid raw commands for repository inspection when RTK equivalents exist. Do not: - use raw `cat` for large files - use raw `grep`/`rg` across the repository - use recursive `find` blindly - inspect large diffs with raw `git diff` - scan directories manually before searching Raw commands are allowed only when: - RTK cannot perform the operation - executing builds/tests/runtime commands - debugging environment/runtime issues - working outside indexed repository scope --- # 📂 CODE NAVIGATION WORKFLOW (MANDATORY) Follow this order when working in the repository. ## 1. Discover Structure ```bash rtk ls ``` ## 2. Search Before Opening Files ```bash rtk grep ``` Examples: ```bash rtk grep "InputComponent" rtk grep "fieldControl" rtk grep "breadcrumbItems" ``` ## 3. Read Only Necessary Files ```bash rtk read ``` ## 4. Large File Strategy For files larger than ~300 lines: ```bash rtk read -l aggressive ``` ## 5. Fast Context Understanding ```bash rtk smart ``` Never: - open many files blindly - read entire modules without searching first - inspect unrelated folders - load generated directories into context --- # 🧠 DIFF INSPECTION RULES For repository changes use: ```bash rtk git diff ``` For large diffs: ```bash rtk git diff -l aggressive ``` Avoid raw: ```bash git diff ``` unless RTK diff is unavailable. --- # 🚫 LOW-VALUE PATHS Avoid loading: ```txt dist/ .angular/ coverage/ node_modules/ .git/ .cache/ .tmp/ ``` unless explicitly required. --- # RTK Usage Rules ## Required RTK Usage - Always use RTK for: - repository indexing - semantic code search - symbol lookup - dependency tracing - architectural context - change impact analysis - Prefer RTK context retrieval over: - reading large files entirely - repeatedly scanning unchanged directories - re-sending full file contents - broad grep operations - Retrieve only the minimal relevant context before making changes. ## Recommended RTK Workflow 1. Index repository 2. Search related symbols/files/components 3. Retrieve minimal context 4. Apply scoped changes 5. Validate impacted areas only Example workflow: ```bash rtk index rtk search "InputComponent number normalization" rtk search "fieldControl" rtk refs "goodListConfig" ``` ## Token Reduction Rules - Never load entire large files unless required. - Never inspect generated folders (`dist`, `.angular`, coverage, etc.). - Prefer symbol-level retrieval over file-level retrieval. - Reuse previously retrieved RTK context whenever possible. - Avoid duplicate searches for the same symbols within one task. - Use targeted searches: - component name - selector - signal/store name - config constant - Angular route - injected service - form control key ## Suggested RTK Queries ### Angular Components ```bash rtk search "selector: 'field-" rtk search "standalone: true" rtk search "InputComponent" ``` ### Forms & Controls ```bash rtk search "fieldControl." rtk search "ControlConfig" rtk search "Validators.required" ``` ### Stores & Signals ```bash rtk search "breadcrumbItems" rtk search "computed(" rtk search "signal(" ``` ### Tenant / Docker ```bash rtk search "DIST_DIR" rtk search "configuration tis" rtk search "prebuild:tis" ``` ### List Configs ```bash rtk search "IListConfig" rtk search "columns:" rtk search "goodListConfig" ``` --- ## Stack Context - Frontend: Angular 20 standalone app. - Package manager: `pnpm`. - Deployment: Docker / Docker Compose with tenant-specific services. - AI-assisted repository navigation: RTK. ### Current service mapping expectation - `app_default` on host port `8090` - `app_tis` on host port `8091` --- ## Tenant Build Rules - `default` tenant currently builds via `ng build` and outputs to `dist/production`. - `tis` tenant builds via `ng build --configuration tis` and outputs to `dist/tis`. - `prebuild:tis` is tenant-scoped and should keep using scripts under `scripts/tis/*`. - Keep Docker `DIST_DIR` aligned with actual Angular output path. - Do not assume `default` Angular configuration is usable unless verified (it may reference missing replacements). - Do not use Angular `fileReplacements` for static assets (`.png`, `.jpg`, etc.); use tenant public assets or prebuild copy scripts. --- ## Tenant PWA Rules - Keep tenant manifest files under tenant public assets (e.g. `public-tis/favicon/site.webmanifest`). - Ensure `manifest` `id`, `start_url`, and `scope` match actual deployment path: - root deploy: `/` - subpath deploy example: `/tis/` - Keep `` path and branding config `manifestPath` aligned. --- ## Input Component Rules File: - `src/app/shared/components/input/input.component.ts` For: - `type === 'number'` - `type === 'price'` Requirements: - Normalize Persian/Arabic digits to English digits. - Allow only digits and `.`. - Support `fixed` precision formatting when provided. Additional rule: - Keep behavior for identifier fields (`mobile`, `phone`, `postalCode`, `nationalId`) string-safe. --- ## Change Policy - Keep changes minimal and scoped to user request. - Prefer root-cause fixes over temporary workarounds. - Avoid unrelated refactors. - Reuse existing patterns and naming conventions. - Use RTK to understand existing patterns before introducing new ones. --- ## Do / Don't ### Do - Follow existing field wrapper style in: - `src/app/shared/components/fields/*.component.ts` - Reuse `app-input` and set only required props: - `type` - `label` - `name` - constraints - Register every new field in: - `src/app/shared/components/fields/index.ts` - `src/app/shared/constants/fields/index.ts` - Keep control keys consistent across: - form group - field component `name` - `fieldControl` key - Use RTK searches before creating new abstractions. ### Don't - Don't add one-off field patterns when an existing field component can be reused. - Don't use invalid Angular file replacements for directories or empty paths. - Don't change tenant output directories without updating Docker `DIST_DIR`. - Don't scan unrelated folders/files when RTK can retrieve exact symbols. - Don't load full files if RTK symbol extraction is sufficient. --- ## How To Create Form Fields - Create a wrapper component in: - `src/app/shared/components/fields` - Use the same pattern as existing files like: - `src/app/shared/components/fields/name.component.ts` - `src/app/shared/components/fields/unit_price.component.ts` Minimal wrapper shape: ```ts @Component({ selector: 'field-example', template: ``, imports: [ReactiveFormsModule, InputComponent], }) export class ExampleComponent { @Input({ required: true }) control = new FormControl(''); @Input() name = 'example'; @Input() label = 'Example'; } ``` --- ## Register New Fields Export the component from: - `src/app/shared/components/fields/index.ts` Add its form control factory in: - `src/app/shared/constants/fields/index.ts` `fieldControl` entry shape: - key must match form control name - return tuple: `[defaultValue, validators]` Example: ```ts example: (value = '', isRequired = true): ControlConfig => [ value, isRequired ? [Validators.required] : [], ], ``` --- ## Using Fields In Forms - In form group builders, use: - `fieldControl.(initialValue, isRequired)` - In templates, render matching wrapper component and pass matching control: - `` - For numeric/price behavior: - use `app-input` - use `type="number"` or `type="price"` - optional `[fixed]` --- ## List Component Configs Centralized list metadata is stored in: - `src/app/shared/constants/list-configs/` Never store configs inside domain modules. ### Structure Structure by data type, not domain: - `good-list.const.ts` - `sku-list.const.ts` - `category-list.const.ts` ### Requirements Each config implements `IListConfig`: - `pageTitle` - `addNewCtaLabel` - `emptyPlaceholderTitle` - `emptyPlaceholderDescription` - `columns` ### Usage ```ts @Input() header: IColumn[] = goodListConfig.columns; listConfig = goodListConfig; ``` ### Rules - Any domain needing a list config imports from: - `@/shared/constants/list-configs` - No cross-domain dependencies. - Do not duplicate configs. --- ## Breadcrumb Usage in Stores & Views - Entity stores expose `breadcrumbItems` as a computed signal. - Call `store.breadcrumbItems()` in view components and extend with current page: ```ts setBreadcrumb() { this.breadcrumbService.setItems([ ...this.store.breadcrumbItems(), { title: 'Current Page' }, ]); } ``` - Root page breadcrumbs are set in the store's `getData()` method once entity is loaded. --- ## Validation Checklist ### TypeScript-only changes ```bash pnpm -s exec tsc -p tsconfig.app.json --noEmit ``` ### Docker/build changes ```bash docker compose build app_default docker compose build app_tis ``` ### Validation Strategy - Start with targeted validation. - Run broader checks only if needed. - Validate only impacted tenants/features when possible. --- ## Communication Expectations - Report exactly which files changed and why. - Call out assumptions and discovered config mismatches. - If validation is blocked: - explain why - provide next command - Mention RTK searches/symbols used when relevant to implementation decisions. --- ## Preferred Investigation Order Before editing code: 1. RTK symbol search 2. Existing implementation discovery 3. Shared abstraction verification 4. Minimal scoped change 5. Targeted validation Avoid: - broad exploratory reads - repeated file dumping - unnecessary context expansion --- ## Angular Architecture Preferences - Prefer standalone components. - Prefer signals/computed over legacy observable-only state when consistent with current architecture. - Keep forms typed. - Keep reusable UI in `shared`. - Keep domain logic outside presentation components. - Preserve existing tenant separation model. --- ## Performance & AI Efficiency - Optimize for: - minimal token usage - minimal file reads - scoped context retrieval - reusable architectural understanding Prefer: - RTK symbol search - targeted reads - incremental inspection Avoid: - dumping full files - repeated repository scans - repeated searches for the same symbols - unnecessary architectural exploration - RTK should be the primary repository understanding tool.