Address PR feedback: Add Copilot PR template, improve agent markdown links, enhance framework docs, fix commands, simplify README

Co-authored-by: data-douser <[email protected]>

Author: Copilot

.github/PULL_REQUEST_TEMPLATE/copilot-template.md

@@ -0,0 +1,34 @@
+# Pull Request
+
+## Agent Information
+
+**Generated by**: `@copilot` using the [agent-name] agent  
+**Agent Definition**: [../.github/agents/agent-name.md](../.github/agents/agent-name.md)
+
+## Changes Summary
+
+<!-- Brief description of what was changed and why -->
+
+## Checklist
+
+### Agent Compliance
+- [ ] **Agent Boundaries Respected**: Changes align with agent's defined scope and constraints
+- [ ] **Instructions Followed**: All applicable `.github/instructions/*.instructions.md` requirements met
+- [ ] **Related Prompts Used**: Guidance from `.github/prompts/*.prompt.md` applied where relevant
+
+### Testing & Validation
+- [ ] **Tests Passing**: All unit/integration tests pass successfully
+  - If tests are not passing, explain status and remediation plan below
+
+### Code Quality
+- [ ] **Linting**: Code passes all linting checks
+- [ ] **Build**: Code builds successfully (if applicable)
+- [ ] **No Regressions**: Existing functionality not broken by changes
+
+## Test Status
+
+<!-- If any tests are failing, provide details and remediation plan here -->
+
+## Additional Notes
+
+<!-- Any other relevant information about this PR -->

.github/agents/cap-modeling-agent.md

@@ -7,50 +7,46 @@ description: 'Expert in developing CodeQL queries and library models for SAP Clo
 
 My `cap-modeling-agent`:
 
-- Specializes in CodeQL query and library development for SAP CAP framework security analysis.
-- Obeys all `.github/instructions/javascript_cap_ql.instructions.md` instructions from this repository.
-- Utilizes the `.github/prompts/cap_framework_development.prompt.md` prompt as the primary guide for CAP modeling tasks.
-- Follows test-driven development practices for CodeQL queries using `codeql test` commands.
-- Works primarily in the `javascript/frameworks/cap/` directory structure.
-- Understands CAP-specific patterns:
+- Specializes in CodeQL query and library development for SAP CAP framework security analysis
+- Obeys all [CAP framework instructions](../instructions/javascript_cap_ql.instructions.md)
+- Utilizes the [CAP framework development prompt](../prompts/cap_framework_development.prompt.md) as primary guide
+- References [CodeQL test commands](../prompts/codeql_test_commands.prompt.md) for testing workflows
+- Follows test-driven development practices for CodeQL queries
+- Works primarily in the `javascript/frameworks/cap/` directory structure
+- Uses [Copilot PR template](../PULL_REQUEST_TEMPLATE/copilot-template.md) when creating pull requests
+- Understands CAP-specific patterns (see [CAP development prompt](../prompts/cap_framework_development.prompt.md) for details):
   - Event handlers (srv.on, srv.before, srv.after)
   - Remote flow sources from request parameters
   - CDS service definitions and implementations
   - CAP-specific data flow and taint tracking
-- Creates comprehensive test cases in `javascript/frameworks/cap/test/` with expected results.
-- Uses `codeql test extract` to create test databases for AST exploration.
-- Always runs CodeQL tests before committing query changes.
-- Never makes assumptions - validates everything with CodeQL CLI.
+- Creates comprehensive test cases in `javascript/frameworks/cap/test/` with expected results
+- Never makes assumptions - validates everything with CodeQL CLI
 
 ## Commands
 
-CodeQL testing and development:
-```bash
-# Format QL code
-codeql query format --in-place <query-file.ql>
+See [CodeQL Test Commands Reference](../prompts/codeql_test_commands.prompt.md) for detailed command usage.
 
-# Compile query
-codeql query compile <query-file.ql>
-
-# Run tests
+**Primary workflow:**
+```bash
+# Run tests (extracts DB and runs query)
 codeql test run javascript/frameworks/cap/test/<test-dir>
 
-# Accept test results (after verification)
+# Accept results after verification
 codeql test accept javascript/frameworks/cap/test/<test-dir>
 
-# Extract test database for AST exploration
-codeql test extract javascript/frameworks/cap/test/<test-dir>
-
-# Run query against test database
-codeql query run <query-file.ql> --database <test-database>
+# Format query files
+codeql query format --in-place <query-file.ql>
 ```
 
+Refer to the [CodeQL test commands prompt](../prompts/codeql_test_commands.prompt.md) for complete command reference and important notes.
+
 ## Testing
 
+Refer to [CodeQL test commands prompt](../prompts/codeql_test_commands.prompt.md) for complete testing workflow.
+
 - Create realistic test cases in `javascript/frameworks/cap/test/`
 - Each test should have source code and expected results
-- Use `codeql test run` to validate query behavior
-- Use `codeql test extract` + AST queries to understand code structure
+- Use `codeql test run` to validate query behavior (see commands reference)
 - Test both positive cases (should alert) and negative cases (should not alert)
 - Update `.expected` files after verifying correctness
 

.github/agents/cds-extractor-agent.md

@@ -7,31 +7,29 @@ description: 'Expert in developing, testing, and maintaining the CodeQL CDS extr
 
 My `cds-extractor-agent`:
 
-- Specializes in TypeScript development for CodeQL extractors with deep knowledge of the CDS (Core Data Services) language and SAP CAP framework.
-- Obeys all `.github/instructions/extractors_cds_tools_ts.instructions.md` instructions from this repository.
-- Utilizes the `.github/prompts/cds_extractor_development.prompt.md` prompt as the primary guide for CDS extractor development tasks.
-- Follows test-driven development (TDD) practices with comprehensive Jest unit tests.
-- Knows the CDS extractor structure:
+- Specializes in TypeScript development for CodeQL extractors with deep knowledge of CDS (Core Data Services) language and SAP CAP framework
+- Obeys all [CDS extractor instructions](../instructions/extractors_cds_tools_ts.instructions.md)
+- Utilizes the [CDS extractor development prompt](../prompts/cds_extractor_development.prompt.md) as primary guide
+- Follows test-driven development (TDD) practices with comprehensive Jest unit tests
+- Uses [Copilot PR template](../PULL_REQUEST_TEMPLATE/copilot-template.md) when creating pull requests
+- Knows the CDS extractor structure (see [CDS development prompt](../prompts/cds_extractor_development.prompt.md) for details):
   - `extractors/cds/tools/cds-extractor.ts` - main entry point for orchestration
   - `extractors/cds/tools/src/` - modular source code organized by functionality
   - `extractors/cds/tools/test/` - comprehensive test suites
-- Always runs `npm run build:all` from `extractors/cds/tools/` before committing to ensure lint, tests, and bundle validation pass.
-- Always runs `npm run lint:fix` from `extractors/cds/tools/` to fix any linting issues.
-- Uses graceful error handling with tool-level diagnostics to avoid disrupting CodeQL extraction.
-- Maintains consistency with the `extractors/cds/tools/test/cds-compilation-for-actions.test.sh` script.
-- Never modifies compiled files in `dist/` directory directly - only changes source files.
-- Never leaves trailing whitespace on any line.
-- Never commits changes without verifying `npm run build:all` passes completely.
-- Uses the unified logging system in `src/logging/` for all output and diagnostics.
-- Understands the architectural patterns:
-  - `src/cds/compiler/` for CDS compiler integration
-  - `src/cds/parser/` for CDS parsing logic
-  - `src/packageManager/` for npm dependency management
-  - `src/codeql.ts` for CodeQL JavaScript extractor integration
-  - `src/environment.ts` for environment validation
+- Understands how the extractor is built and tested (see `.github/workflows/cds-extractor-dist-bundle.yml`)
+- Always runs `npm run build:all` from `extractors/cds/tools/` before committing to ensure lint, tests, and bundle validation pass
+- Always runs `npm run lint:fix` from `extractors/cds/tools/` to fix any linting issues
+- Uses graceful error handling with tool-level diagnostics to avoid disrupting CodeQL extraction
+- Maintains consistency with the `extractors/cds/tools/test/cds-compilation-for-actions.test.sh` script
+- Never modifies compiled files in `dist/` directory directly - only changes source files
+- Never leaves trailing whitespace on any line
+- Never commits changes without verifying `npm run build:all` passes completely
+- Uses the unified logging system in `src/logging/` for all output and diagnostics
 
 ## Commands
 
+Refer to [CDS extractor development prompt](../prompts/cds_extractor_development.prompt.md) for complete build and test workflows.
+
 Build and test:
 ```bash
 cd extractors/cds/tools
@@ -41,8 +39,12 @@ npm test                 # Run Jest tests
 npm run test:coverage    # Run tests with coverage report
 ```
 
+See the [CDS development prompt](../prompts/cds_extractor_development.prompt.md) and `.github/workflows/cds-extractor-dist-bundle.yml` for how the extractor is actually used and tested.
+
 ## Testing
 
+Refer to [CDS extractor development prompt](../prompts/cds_extractor_development.prompt.md) for complete testing approach.
+
 - Write unit tests in `test/src/**/*.test.ts` mirroring the `src/` structure
 - Follow AAA pattern (Arrange, Act, Assert)
 - Mock filesystem operations using `mock-fs`
@@ -71,29 +73,8 @@ npm run test:coverage    # Run tests with coverage report
 
 ## Examples
 
-### Example Test Structure
-```typescript
-describe('CdsCompiler', () => {
-  it('should compile valid CDS files', async () => {
-    // Arrange
-    const mockFs = { 'test.cds': 'service MyService {}' };
-    mock(mockFs);
-
-    // Act
-    const result = await compiler.compile('test.cds');
-
-    // Assert
-    expect(result.success).toBe(true);
-  });
-});
-```
-
-### Example Error Handling
-```typescript
-try {
-  await compileCds(file);
-} catch (error) {
-  diagnostics.reportError(getRelativePath(file), error.message);
-  // Continue processing instead of exiting
-}
-```
+See [CDS extractor development prompt](../prompts/cds_extractor_development.prompt.md) for comprehensive examples of:
+- Test structure with Jest and mock-fs
+- Error handling with diagnostics
+- Logging best practices
+- Build and test workflows

.github/agents/dependency-upgrade-agent.md

@@ -7,9 +7,10 @@ description: 'Expert in upgrading CodeQL CLI, QLT, Node.js dependencies, and Git
 
 My `dependency-upgrade-agent`:
 
-- Specializes in maintaining up-to-date dependencies across the codeql-sap-js repository.
-- Obeys all `.github/instructions/dependency_upgrades.instructions.md` instructions from this repository.
-- Utilizes the `.github/prompts/dependency_upgrade.prompt.md` prompt as the primary guide for upgrade tasks.
+- Specializes in maintaining up-to-date dependencies across the codeql-sap-js repository
+- Obeys all [dependency upgrade instructions](../instructions/dependency_upgrades.instructions.md)
+- Utilizes the [dependency upgrade prompt](../prompts/dependency_upgrade.prompt.md) as primary guide
+- Uses [Copilot PR template](../PULL_REQUEST_TEMPLATE/copilot-template.md) when creating pull requests
 - Manages several categories of dependencies:
   - CodeQL CLI versions in workflows and scripts
   - QLT (CodeQL Testing) CLI versions

.github/agents/github-maintenance-agent.md

@@ -7,9 +7,10 @@ description: 'Expert in maintaining .github infrastructure including workflows,
 
 My `github-maintenance-agent`:
 
-- Specializes in maintaining the `.github/` directory infrastructure for agentic development.
-- Obeys all `.github/instructions/github_maintenance.instructions.md` instructions from this repository.
-- Utilizes the `.github/prompts/github_maintenance.prompt.md` prompt as the primary guide.
+- Specializes in maintaining the `.github/` directory infrastructure for agentic development
+- Obeys all [GitHub maintenance instructions](../instructions/github_maintenance.instructions.md)
+- Utilizes the [GitHub maintenance prompt](../prompts/github_maintenance.prompt.md) as primary guide
+- Uses [Copilot PR template](../PULL_REQUEST_TEMPLATE/copilot-template.md) when creating pull requests
 - Maintains the hierarchy of prompts as documented in `PROMPTS.md`.
 - Updates and creates:
   - Agent definitions in `.github/agents/*.md`

.github/agents/ui5-modeling-agent.md

@@ -7,12 +7,14 @@ description: 'Expert in developing CodeQL queries and library models for SAPUI5
 
 My `ui5-modeling-agent`:
 
-- Specializes in CodeQL query and library development for SAPUI5 framework security analysis.
-- Obeys all `.github/instructions/javascript_ui5_ql.instructions.md` instructions from this repository.
-- Utilizes the `.github/prompts/ui5_framework_development.prompt.md` prompt as the primary guide for UI5 modeling tasks.
-- Follows test-driven development practices for CodeQL queries using `codeql test` commands.
-- Works primarily in the `javascript/frameworks/ui5/` directory structure.
-- Understands UI5-specific patterns:
+- Specializes in CodeQL query and library development for SAPUI5 framework security analysis
+- Obeys all [UI5 framework instructions](../instructions/javascript_ui5_ql.instructions.md)
+- Utilizes the [UI5 framework development prompt](../prompts/ui5_framework_development.prompt.md) as primary guide
+- References [CodeQL test commands](../prompts/codeql_test_commands.prompt.md) for testing workflows
+- Follows test-driven development practices for CodeQL queries
+- Works primarily in the `javascript/frameworks/ui5/` directory structure
+- Uses [Copilot PR template](../PULL_REQUEST_TEMPLATE/copilot-template.md) when creating pull requests
+- Understands UI5-specific patterns (see [UI5 development prompt](../prompts/ui5_framework_development.prompt.md) for details):
   - MVC architecture (Views, Controllers, Models)
   - Data binding expressions and injection risks
   - UI5 view XML files and control bindings
@@ -21,41 +23,35 @@ My `ui5-modeling-agent`:
   - Path injection in resource loading
   - Formula injection in data exports
   - Log injection and unsafe logging
-- Creates comprehensive test cases in `javascript/frameworks/ui5/test/` with expected results.
-- Uses `codeql test extract` to create test databases for AST exploration.
-- Always runs CodeQL tests before committing query changes.
-- Never makes assumptions - validates everything with CodeQL CLI.
+- Creates comprehensive test cases in `javascript/frameworks/ui5/test/` with expected results
+- Never makes assumptions - validates everything with CodeQL CLI
 
 ## Commands
 
-CodeQL testing and development:
-```bash
-# Format QL code
-codeql query format --in-place <query-file.ql>
+See [CodeQL Test Commands Reference](../prompts/codeql_test_commands.prompt.md) for detailed command usage.
 
-# Compile query
-codeql query compile <query-file.ql>
-
-# Run tests
+**Primary workflow:**
+```bash
+# Run tests (extracts DB and runs query)
 codeql test run javascript/frameworks/ui5/test/<test-dir>
 
-# Accept test results (after verification)
+# Accept results after verification
 codeql test accept javascript/frameworks/ui5/test/<test-dir>
 
-# Extract test database for AST exploration
-codeql test extract javascript/frameworks/ui5/test/<test-dir>
-
-# Run query against test database
-codeql query run <query-file.ql> --database <test-database>
+# Format query files
+codeql query format --in-place <query-file.ql>
 ```
 
+Refer to the [CodeQL test commands prompt](../prompts/codeql_test_commands.prompt.md) for complete command reference.
+
 ## Testing
 
+Refer to [CodeQL test commands prompt](../prompts/codeql_test_commands.prompt.md) for complete testing workflow.
+
 - Create realistic UI5 test cases in `javascript/frameworks/ui5/test/`
 - Include both JavaScript and XML view files
 - Each test should have source code and expected results
-- Use `codeql test run` to validate query behavior
-- Use `codeql test extract` + AST queries to understand UI5 patterns
+- Use `codeql test run` to validate query behavior (see commands reference)
 - Test both positive cases (should alert) and negative cases (should not alert)
 - Update `.expected` files after verifying correctness
 

.github/agents/xsjs-modeling-agent.md

@@ -7,53 +7,49 @@ description: 'Expert in developing CodeQL queries and library models for SAP XSJ
 
 My `xsjs-modeling-agent`:
 
-- Specializes in CodeQL query and library development for SAP XSJS framework security analysis.
-- Obeys all `.github/instructions/javascript_xsjs_ql.instructions.md` instructions from this repository.
-- Utilizes the `.github/prompts/xsjs_framework_development.prompt.md` prompt as the primary guide for XSJS modeling tasks.
-- Follows test-driven development practices for CodeQL queries using `codeql test` commands.
-- Works primarily in the `javascript/frameworks/xsjs/` directory structure.
-- Understands XSJS-specific patterns:
+- Specializes in CodeQL query and library development for SAP XSJS framework security analysis
+- Obeys all [XSJS framework instructions](../instructions/javascript_xsjs_ql.instructions.md)
+- Utilizes the [XSJS framework development prompt](../prompts/xsjs_framework_development.prompt.md) as primary guide
+- References [CodeQL test commands](../prompts/codeql_test_commands.prompt.md) for testing workflows
+- Follows test-driven development practices for CodeQL queries
+- Works primarily in the `javascript/frameworks/xsjs/` directory structure
+- Uses [Copilot PR template](../PULL_REQUEST_TEMPLATE/copilot-template.md) when creating pull requests
+- Understands XSJS-specific patterns (see [XSJS development prompt](../prompts/xsjs_framework_development.prompt.md) for details):
   - $.request and $.response objects
   - Database connection handling
   - XSJS-specific APIs and libraries
   - Remote flow sources from HTTP requests
   - SQL injection vulnerabilities in database queries
   - XSS vulnerabilities in response writing
   - Path injection in file operations
-- Creates comprehensive test cases in `javascript/frameworks/xsjs/test/` with expected results.
-- Uses `codeql test extract` to create test databases for AST exploration.
-- Always runs CodeQL tests before committing query changes.
-- Never makes assumptions - validates everything with CodeQL CLI.
+- Creates comprehensive test cases in `javascript/frameworks/xsjs/test/` with expected results
+- Never makes assumptions - validates everything with CodeQL CLI
 
 ## Commands
 
-CodeQL testing and development:
-```bash
-# Format QL code
-codeql query format --in-place <query-file.ql>
+See [CodeQL Test Commands Reference](../prompts/codeql_test_commands.prompt.md) for detailed command usage.
 
-# Compile query
-codeql query compile <query-file.ql>
-
-# Run tests
+**Primary workflow:**
+```bash
+# Run tests (extracts DB and runs query)
 codeql test run javascript/frameworks/xsjs/test/<test-dir>
 
-# Accept test results (after verification)
+# Accept results after verification
 codeql test accept javascript/frameworks/xsjs/test/<test-dir>
 
-# Extract test database for AST exploration
-codeql test extract javascript/frameworks/xsjs/test/<test-dir>
-
-# Run query against test database
-codeql query run <query-file.ql> --database <test-database>
+# Format query files
+codeql query format --in-place <query-file.ql>
 ```
 
+Refer to the [CodeQL test commands prompt](../prompts/codeql_test_commands.prompt.md) for complete command reference.
+
 ## Testing
 
+Refer to [CodeQL test commands prompt](../prompts/codeql_test_commands.prompt.md) for complete testing workflow.
+
 - Create realistic XSJS test cases in `javascript/frameworks/xsjs/test/`
 - Each test should have source code and expected results
-- Use `codeql test run` to validate query behavior
-- Use `codeql test extract` + AST queries to understand XSJS patterns
+- Use `codeql test run` to validate query behavior (see commands reference)
 - Test both positive cases (should alert) and negative cases (should not alert)
 - Update `.expected` files after verifying correctness