psp_panel/agents.md

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:

git status        -> rtk git status
git diff          -> rtk git diff
git log           -> rtk git log
ls                -> rtk ls
tree              -> rtk ls
cat <file>        -> rtk read <file>
grep <pattern>    -> rtk grep <pattern>
rg <pattern>      -> rtk grep <pattern>
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

rtk ls

2. Search Before Opening Files

rtk grep <symbol | class | function | DTO | service>

Examples:

rtk grep "InputComponent"
rtk grep "fieldControl"
rtk grep "breadcrumbItems"

3. Read Only Necessary Files

rtk read <file>

4. Large File Strategy

For files larger than ~300 lines:

rtk read <file> -l aggressive

5. Fast Context Understanding

rtk smart <file>

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:

rtk git diff

For large diffs:

rtk git diff -l aggressive

Avoid raw:

git diff

unless RTK diff is unavailable.

---

🚫 LOW-VALUE PATHS

Avoid loading:

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:

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

rtk search "selector: 'field-"
rtk search "standalone: true"
rtk search "InputComponent"

Forms & Controls

rtk search "fieldControl."
rtk search "ControlConfig"
rtk search "Validators.required"

Stores & Signals

rtk search "breadcrumbItems"
rtk search "computed("
rtk search "signal("

Tenant / Docker

rtk search "DIST_DIR"
rtk search "configuration tis"
rtk search "prebuild:tis"

List Configs

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 <link rel="manifest"> 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:

@Component({
  selector: 'field-example',
  template: `<app-input [label]="label" [control]="control" [name]="name" type="simple" />`,
  imports: [ReactiveFormsModule, InputComponent],
})
export class ExampleComponent {
  @Input({ required: true }) control = new FormControl<string>('');
  @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:

example: (value = '', isRequired = true): ControlConfig => [
  value,
  isRequired ? [Validators.required] : [],
],

---

Using Fields In Forms

• In form group builders, use:
  • fieldControl.<key>(initialValue, isRequired)
• In templates, render matching wrapper component and pass matching control:
  • <field-example [control]="form.controls.example" />
• 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

@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:

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

pnpm -s exec tsc -p tsconfig.app.json --noEmit

Docker/build changes

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.