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.

---

# ⚡ EXECUTION RULES (STRICT)

Minimize reasoning verbosity.

## Response Style

Do not:
- narrate thoughts
- speculate
- explain obvious steps
- describe intentions before acting
- write reflective/internal commentary

Avoid messages like:
- "I think I need to..."
- "I should inspect..."
- "I'm going to..."
- "I wonder if..."
- "Let me check..."
- "I'm curious about..."

Instead:
- act immediately
- use short operational updates only when necessary

Good:

Inspecting environment files and Angular configs.

Bad:

I think I should inspect the environment files first to understand how everything is connected before deciding what changes are necessary.


---

# 🔇 MINIMAL PLANNING MODE

Only create plans when:
- task has multiple independent phases
- task is ambiguous
- task is large/refactor-level

Do not create plans for:
- small fixes
- single-file edits
- obvious tasks

Avoid:
- repeated plan updates
- verbose planning
- unnecessary decomposition

---

# ✂️ MINIMAL OUTPUT RULES

Keep responses compact.

Do not:
- restate the user request
- explain already-visible edits
- summarize trivial findings
- narrate file discovery
- explain failed reads unless blocking
- describe obvious implementation details

Prefer:

Updated environment files for development, staging, production, and tis.

Avoid:

I found a mismatch and then investigated several files before determining that...

---

# 📦 FINAL RESPONSE RULES

Final responses must be under 10 lines unless:

- user explicitly asks for explanation
- architectural decisions changed
- validation failed
- multiple systems were affected

Prefer:

Updated:
- file1
- file2

Validation:
- pnpm tsc passed

Avoid:

- long prose summaries
- unnecessary explanations
- repeating repository context

---

# 🚫 NO TEACHING MODE

Do not explain:

- Angular basics
- TypeScript basics
- RxJS basics
- obvious framework behavior
- standard programming concepts

Assume repository maintainers already understand the stack.

---

# 🧠 CONTEXT PRESERVATION RULES

Avoid repeating previously established context.

Do not repeatedly mention:
- repository structure
- framework details
- previously inspected files
- known architecture
- already-established conventions

Assume prior context remains valid unless changed.

---

# 🛑 EXPLORATION STOP RULE

If the likely edit location is identified:

- stop searching
- stop exploring
- implement changes

Do not continue repository exploration after:

- target component found
- target service found
- target config found
- target store found
- target route found

---

# 🎯 EDIT-FIRST BEHAVIOR

After identifying the target location:

- edit quickly
- avoid excessive inspection
- avoid repeated verification reads
- avoid speculative exploration

Prefer implementation over exploration.

---

# ✍️ EDIT CONFIDENCE RULES

Prefer direct implementation when:

- existing patterns are obvious
- nearby components establish conventions
- requested change is localized
- existing abstractions already match requirements

Do not over-investigate obvious implementations.

---

# ⚠️ FAILURE HANDLING RULES

If a file read fails:

- do not retry repeatedly
- verify path once
- continue with nearest valid target

Do not:

- repeatedly attempt missing files
- scan nearby directories unnecessarily
- speculate about missing files
- retry identical commands

---

# 📏 HARD CONTEXT LIMITS

Do not:

- read more than 2 files before first edit
- read more than 1 sibling file unless required
- reread unchanged files
- inspect unrelated modules

For small tasks:

- maximum 3 repository reads before editing

For medium tasks:

- maximum 8 repository reads before editing

Large/refactor tasks may exceed limits only when necessary.

---

# 🚫 AVOID MULTI-FILE EAGER READS

Never chain multiple reads in one command unless necessary.

Avoid:

- rtk read a.ts && rtk read b.ts && rtk read c.ts

Prefer sequential targeted reads.

---


# ✅ 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

---



# 🧩 FILE READING RULES (IMPORTANT)

Prefer minimal-context reads.

## Preferred Order

1. `rtk grep`
2. `rtk smart`
3. `rtk read`
4. aggressive read only if required

## Rules

Never immediately read a full file after search.

Before reading:
- identify exact symbol/component/function
- inspect only relevant sections

Prefer:

- rtk smart <file>

before:

- rtk read <file>


For large files:

- rtk read <file> -l aggressive


Only when necessary.

Avoid:
- reading TS + HTML + SCSS together
- opening sibling files preemptively
- rereading files already inspected
- reading generated or unrelated files

---

## Angular-Specific Strategy

For Angular components:

1. grep component selector/class
2. smart-read TS file
3. read template only if UI changes required
4. read styles only if styling changes required

Example:

bash
rtk grep "invoice-type-card"
rtk smart invoice-type-card.component.ts
rtk read invoice-type-card.component.html


Avoid:

bash
rtk read component.ts
rtk read component.html
rtk read component.scss


unless all files are actually needed.

# 📂 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 <symbol | class | function | DTO | service>


Examples:

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


## 3. Read Only Necessary Files

bash
rtk read <file>


## 4. Large File Strategy

For files larger than ~300 lines:

bash
rtk read <file> -l aggressive


## 5. Fast Context Understanding

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

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:


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

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

ts
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

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.