pi-apexlang 0.1.0

package/skills/apexlang/templates/shared-components/ai-agents/ai-agents.ai-tools.augment-system-prompt.md

@@ -0,0 +1,71 @@
+---
+templateId: ai-agents.ai-tools.augment-system-prompt.md
+componentType: aiAgents
+version: 1.0
+description: AI Tool used to retrieve data to augment the system prompt
+---
+
+# Purpose
+
+Standard AI Agent contract for data-retrieval tool to augment the system prompt.
+
+This tool will retrieve data based on the results of a SQL query and use that to augment the system prompt.  This is useful for dynamic content that is specific to a user or scenario.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Keep SQL deterministic and scoped to the tool's purpose.
+2. When querying real tables or views, use metadata-verified columns only and align with the database rules in `references/policies/memory-bank/00-guard/ai.guard.md`.
+3. Render Augment System Prompt tool settings as inline scalar properties. Do not wrap `settings.dataDescription`, `settings.sqlQuery`, or client-side `settings.jsCode` in fenced code blocks.
+4. Do not emit a top-level `description:` property for Augment System Prompt tools unless runtime metadata proves it is accepted for that execution point; use `settings.dataDescription` for retrieve-data context.
+5. Keep `settings.sqlQuery` short enough to fit inline on the property value. Prefer a compact one-line query for Augment System Prompt tools.
+6. Keep the raw body of `settings.sqlQuery` at or below 4000 characters.
+7. If the SQL body would exceed 4000 characters:
+   - move prompt-independent joins, aggregations, and normalization into secure view(s)
+   - keep `settings.sqlQuery` as a short wrapper query over those view(s)
+   - when the tool uses `:APEX$AI_LAST_USER_PROMPT` or `:APEX$AI_ALL_USER_PROMPTS`, keep only the prompt-aware filtering or scoring logic inline
+8. If the prompt-aware wrapper still cannot be reduced below 4000 characters, stop with Missing Inputs instead of emitting oversized inline SQL.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| name | yes | string | Static ID of the AI tool; lower case, no spaces, use `-`. |
+| tool.name | yes | string | Friendly execution name; lower case, no spaces, use `_`. |
+| settings.dataDescription | no | string | Inline scalar description of the data sent to the AI service. Do not use a fenced block. |
+| settings.sqlQuery | yes | string | Inline scalar SQL query ending with `;`. Do not use a fenced block. Keep at or below 4000 characters; if more logic is required, move prompt-independent work into secure view(s) and keep this query as a short wrapper. |
+| serverSideCondition.type | no | string | Use only supported condition types from `references/policies/memory-bank/20-data/apex.logic.md`. |
+| serverSideCondition.list | no | string |
+| security.authorizationScheme | no | string | The name of the Authorization Scheme associated with this tool
+
+---
+
+# Conditional Rendering Rules
+
+- Only render `settings.dataDescription` if there is a value, and render it as `dataDescription: ...` on one line.
+- Only render `serverSideCondition {}` if there is a value.
+- Only render `security {}` if there is a value.
+- Render `settings.sqlQuery` as `sqlQuery: {{settings.sqlQuery}};` without triple backticks.
+- All other sections should always be rendered.
+
+---
+
+# Output Template — AI Tool
+```
+    tool {{name}} (
+        name: {{tool.name}}
+        type: retrieveData
+        executionPoint: augmentSystemPrompt
+        settings {
+            dataDescription: {{settings.dataDescription}}
+            sqlQuery: {{settings.sqlQuery}};
+        }
+        {{serverSideConditionBlock}}
+        {{securityBlock}}
+    )
+```
+
+---

package/skills/apexlang/templates/shared-components/ai-agents/ai-agents.ai-tools.execute-code-client-js.md

@@ -0,0 +1,87 @@
+---
+templateId: ai-agents.ai-tools.execute-code-client-js.md
+componentType: aiAgents
+version: 1.0
+description: AI Tool used to execute JavaScript code
+imports:
+  - ai-agents.at-tools.parameters.md
+---
+
+# Purpose
+
+Standard AI Agent contract for action-oriented tools that execute client-side JavaScript.
+
+This tool is intended for browser-side interactions or validations that should run on demand.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Replace the `{{parameters}}` section with a list of concrete parameters from `ai-agents.at-tools.parameters.md`.
+2. Keep JavaScript concise and deterministic.
+3. Use `settings.jsCode` for executable logic and keep the implementation focused on a single client-side responsibility.
+4. For `executionPoint: augmentSystemPrompt`, render `settings.jsCode` inline as a scalar value and do not use a fenced JavaScript block.
+5. For `executionPoint: augmentSystemPrompt`, omit the top-level `description:` property unless runtime metadata proves it is accepted for that execution point.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| name | yes | string | Static ID of the AI tool; lower case, no spaces, use `-`. |
+| tool.name | yes | string | Friendly execution name; lower case, no spaces, use `_`. |
+| description.description | no | string | Description of the tool; recommended because this acts as the prompt for the tool
+| notification.message | no | string | Optional notification displayed once the tool has completed |
+| notification.type | no | string | Notification type: `info`, `generic`, or `success` |
+| executionPoint | yes | enum | Use `onDemand` for interactive browser-side actions. Use `augmentSystemPrompt` for lightweight context captured on every prompt, such as browser timezone. |
+| settings.jsCode | yes | string | JavaScript code executed by the tool on the client. Render inline for `augmentSystemPrompt`; render fenced for `onDemand`. |
+
+---
+
+# Conditional Rendering Rules
+
+- Only render `notification {}` if there is a value.
+- For `augmentSystemPrompt`, do not render `description`, `notification`, or `parameter` blocks.
+- All other sections should always be rendered.
+
+---
+
+# Output Template — AI Tool
+
+## On Demand
+```
+    tool {{name}} (
+        name: {{tool.name}}
+        type: executeClientsideCode
+        executionPoint: onDemand
+        description:
+            ```
+            {{description}}
+            ```
+        {{notificationBlock}}
+        settings {
+            jsCode:
+                ```javascript-browser
+                {{settings.jsCode}}
+                ```
+        }
+        {{parameters}}
+
+    )
+```
+
+## Augment System Prompt
+```
+    tool {{name}} (
+        name: {{tool.name}}
+        type: executeClientsideCode
+        executionPoint: augmentSystemPrompt
+        settings {
+            jsCode: {{settings.jsCode}};
+        }
+
+    )
+```
+
+---

package/skills/apexlang/templates/shared-components/ai-agents/ai-agents.ai-tools.execute-code-server-js.md

@@ -0,0 +1,70 @@
+---
+templateId: ai-agents.ai-tools.execute-code-server-js.md
+componentType: aiAgents
+version: 1.0
+description: AI Tool used to execute server-side JavaScript code
+imports:
+  - ai-agents.at-tools.parameters.md
+---
+
+# Purpose
+
+Standard AI Agent contract for action-oriented tools that execute server-side JavaScript.
+
+This tool is intended for server-side updates or validations that should run on demand.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Replace the `{{parameters}}` section with a list of concrete parameters from `ai-agents.at-tools.parameters.md`.
+2. Keep JavaScript concise and deterministic.
+3. Use `settings.jsCode` for executable logic and keep the implementation focused on a single tool responsibility.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| name | yes | string | Static ID of the AI tool; lower case, no spaces, use `-`. |
+| tool.name | yes | string | Friendly execution name; lower case, no spaces, use `_`. |
+| description.description | no | string | Description of the tool; recommended because this acts as the prompt for the tool
+| notification.message | no | string | Optional notification displayed once the tool has completed |
+| notification.type | no | string | Notification type: `info`, `generic`, or `success` |
+| settings.jsCode | yes | string | JavaScript code executed by the tool |
+
+---
+
+# Conditional Rendering Rules
+
+- Only render `notification {}` if there is a value.
+- All other sections should always be rendered.
+
+---
+
+# Output Template — AI Tool
+```
+    tool {{name}} (
+        name: {{tool.name}}
+        type: executeServersideCode
+        executionPoint: onDemand
+        description:
+            ```
+            {{description}}
+            ```
+        {{notificationBlock}}
+        settings {
+            language: js-mle
+            jsCode:
+                ```javascript-mle
+                {{settings.jsCode}}
+                ```
+        }
+
+        {{parameters}}
+
+    )
+```
+
+---

package/skills/apexlang/templates/shared-components/ai-agents/ai-agents.ai-tools.execute-code-server-plsql.md

@@ -0,0 +1,92 @@
+---
+templateId: ai-agents.ai-tools.execute-code-server-plsql.md
+componentType: aiAgents
+version: 1.0
+description: AI Tool used to execute PL/SQL code
+imports:
+  - ai-agents.at-tools.parameters.md
+---
+
+# Purpose
+
+Standard AI Agent contract for action-oriented tools that execute PL/SQL.
+
+This tool is intended for server-side updates or validations that should run on demand.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Replace the `{{parameters}}` section with a list of concrete parameters from `ai-agents.at-tools.parameters.md`.
+2. Keep PL/SQL concise and deterministic.
+3. Use named notation for packaged procedure or function calls.
+4. If the PL/SQL block would exceed 4000 characters, or if it performs multi-step DML, orchestration, or non-trivial business validation, move the logic into a packaged procedure or function owned by the application schema.
+5. Expected validation or business-rule outcomes may follow the application's chosen runtime pattern:
+   - surface a clear user-facing validation or business-rule message from a packaged procedure, or
+   - return a handled user-facing success/error message from a packaged function.
+6. When the tool needs to surface a success, error, info, or warning response, use `apex_ai.set_tool_result(...)` in `settings.plsqlCode` to populate:
+   - `p_result` for the business result name or validation name
+   - `p_notification_message` for the user-facing message
+   - `p_notification_type` using one of `success`, `error`, `info`, or `warning`
+7. When logic is moved into a package, keep `settings.plsqlCode` as a thin wrapper that calls that package using named notation only and maps the package outcome into `apex_ai.set_tool_result(...)`.
+8. If the required packaged database object does not yet exist, add it through the application's supporting objects or stop with Missing Inputs when that is out of scope.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| name | yes | string | Static ID of the AI tool; lower case, no spaces, use `-`. |
+| tool.name | yes | string | Friendly execution name; lower case, no spaces, use `_`. |
+| description.description | no | string | Description of the tool; recommended because this acts as the prompt for the tool
+| notification.message | no | string | Optional notification displayed once the tool has completed |
+| notification.type | no | string | Notification type: `info`, `generic`, or `success` |
+| settings.plsqlCode | yes | plsql | PL/SQL block executed by the tool. Prefer a thin wrapper when heavy logic lives in a package and use `apex_ai.set_tool_result(...)` to return the business result plus the user-facing notification. |
+
+---
+
+# Conditional Rendering Rules
+
+- Only render `notification {}` if there is a value.
+- For heavy action logic, render only a short wrapper block in `settings.plsqlCode` and keep the full implementation in a packaged procedure/function.
+- All other sections should always be rendered.
+
+---
+
+# Guardrail Notes
+
+- Treat packaged procedures/functions as the default destination for large or business-critical action logic.
+- Inline PL/SQL is appropriate only for small, local, deterministic actions.
+- When a package call is used, pass inputs with named notation and keep the AI tool block easy to review.
+- If the application uses packaged procedures for action tools, surface clear business-validation messages from those procedures instead of forcing a separate message-return function.
+- If the application uses packaged functions for action tools, map the returned values into `apex_ai.set_tool_result(...)` and do not assume a generic PL/SQL `return <expr>` pattern is valid.
+- Reserve low-signal raw database errors for truly unexpected failures; expected business validations should surface as clear user-facing messages.
+
+---
+
+# Output Template — AI Tool
+```
+    tool {{name}} (
+        name: {{tool.name}}
+        type: executeServersideCode
+        executionPoint: onDemand
+        description:
+            ```
+            {{description}}
+            ```
+        {{notificationBlock}}
+        settings {
+            language: plsql
+            plsqlCode:
+                ```plsql
+                {{settings.plsqlCode}}
+                ```
+        }
+
+        {{parameters}}
+
+    )
+```
+
+---

package/skills/apexlang/templates/shared-components/ai-agents/ai-agents.ai-tools.md

@@ -0,0 +1,36 @@
+---
+templateId: ai-agents.ai-tools
+componentType: aiAgents
+version: 1.0
+description: Canonical contract and guardrails for AI Agent tools
+---
+
+# Purpose
+
+Standard AI Agent tools contract; required as a parent container for all AI tools.
+
+This document lists the available AI tools and describes the function of each one.
+
+
+| Tool | Filename | Description |
+|------|----------|-------------|
+| Retrieve Data via SQL | `ai-agents.ai-tools.retrieve-data-sql.md` | Retrieves data from the database as CSV output
+| Augment System Prompt | `ai-agents.ai-tools.augment-system-prompt.md` | Retrieves data from the database and used that to augment the system prompt
+| Execute Server-Side PL/SQL | `ai-agents.ai-tools.execute-code-server-plsql.md` | Executes server-side PL/SQL to update or validate application data
+| Execute Server-Side JavaScript | `ai-agents.ai-tools.execute-code-server-js.md` | Executes server-side JavaScript in the database using MLE
+| Execute Client-Side JavaScript | `ai-agents.ai-tools.execute-code-client-js.md` | Executes client-side JavaScript in the browser for on-demand interactions or validations
+
+
+
+
+## Rules
+
+1. Tools that use PL/SQL can refer to parameters using the `:PARAMETER_NAME` syntax.
+2. Keep tool static IDs (`tool <id>`) lower case with `-` separators when needed.
+3. Keep tool execution names (`name:`) lower case with `_` separators when needed.
+4. Use `ai-agents.at-tools.parameters.md` for parameter blocks instead of inventing custom parameter shapes.
+5. Use only documented blocks and attributes so generated output stays aligned with the shared-component template rules.
+6. Augment System Prompt tools use inline scalar settings syntax:
+   - Retrieve Data: `dataDescription: ...` and `sqlQuery: select ...;`
+   - Execute Client-Side Code: `jsCode: return ...;`
+   - Do not emit fenced code blocks, top-level `description`, notifications, or parameters for Augment System Prompt tools.

package/skills/apexlang/templates/shared-components/ai-agents/ai-agents.ai-tools.retrieve-data-sql.md

@@ -0,0 +1,99 @@
+---
+templateId: ai-agents.ai-tools.retrieve-data-sql.md
+componentType: aiAgents
+version: 1.0
+description: AI Tool used to retrieve data via SQL Query
+imports:
+  - ai-agents.at-tools.parameters.md
+---
+
+# Purpose
+
+Standard AI Agent contract for data-retrieval tools.
+
+This tool will retrieve data based on the results of a SQL query.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Replace the `{{parameters}}` section with a list of concrete parameters from `ai-agents.at-tools.parameters.md`.
+2. For any structured lookup or filter input that can be named up front, declare one or more explicit `parameter (...)` blocks and bind those parameters inside `settings.sqlQuery`.
+3. Do not use `:APEX$AI_LAST_USER_PROMPT` or `:APEX$AI_ALL_USER_PROMPTS` as a surrogate for explicit tool parameters when the tool is expected to accept stable business inputs such as IDs, numbers, codes, names, statuses, types, dates, or other declarative filters.
+4. Use `:APEX$AI_LAST_USER_PROMPT` or `:APEX$AI_ALL_USER_PROMPTS` only when the tool genuinely needs free-text reasoning support that cannot be represented cleanly as explicit parameters, such as fallback keyword ranking, semantic hinting, or broad exploratory search approved by the workflow.
+5. Keep SQL deterministic and scoped to the tool's purpose.
+6. When querying real tables or views, use metadata-verified columns only and align with the database rules in `references/policies/memory-bank/00-guard/ai.guard.md`.
+7. Keep the raw body of `settings.sqlQuery` at or below 4000 characters.
+8. If the SQL body would exceed 4000 characters:
+   - move prompt-independent joins, aggregations, and normalization into secure view(s)
+   - keep `settings.sqlQuery` as a short wrapper query over those view(s)
+   - if the tool legitimately uses `:APEX$AI_LAST_USER_PROMPT` or `:APEX$AI_ALL_USER_PROMPTS`, keep only the prompt-aware filtering or scoring logic inline
+9. If the wrapper still cannot be reduced below 4000 characters, stop with Missing Inputs instead of emitting oversized inline SQL.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| name | yes | string | Static ID of the AI tool; lower case, no spaces, use `-`. |
+| tool.name | yes | string | Friendly execution name; lower case, no spaces, use `_`. |
+| description.description | no | string | Description of the tool; optional, but strongly recommended as this acts as the prompt for the tool
+| notification.message | no | string | Specify an optional notification to be displayed once the tool has completed.
+| notification.type | no | string | Specify the type of notification: `info`, `generic` or `success`
+| settings.dataDescription | no | string | Enter a brief description of the data that will be sent to the AI service. This description should clearly explain the nature and content of the data being provided, helping the AI to better understand and process the information.
+| settings.sqlQuery | yes | string | Specify the SQL query that generates the CSV output as context for the AI service. Keep the raw body at or below 4000 characters. Prefer explicit tool parameters for stable inputs and bind them directly in the SQL. Use the special prompt binds only for approved free-text reasoning scenarios that cannot be modeled cleanly as parameters: **APEX$AI_LAST_USER_PROMPT** contains the most recent user-entered prompt and **APEX$AI_ALL_USER_PROMPTS** contains all user prompts concatenated together. |
+| serverSideCondition.type | no | string | Use only supported condition types from `references/policies/memory-bank/20-data/apex.logic.md`. |
+| serverSideCondition.list | no | string |
+| security.authorizationScheme | no | string | The name of the Authorization Scheme associated with this tool
+
+---
+
+# Conditional Rendering Rules
+
+- Only render `notification {}` if there is a value.
+- Only render `settings.dataDescription` if there is a value.
+- Only render `serverSideCondition {}` if there is a value.
+- Only render `security {}` if there is a value.
+- When the tool accepts structured business filters, render explicit `parameter (...)` blocks and bind those parameters in the SQL instead of reading the raw prompt text directly.
+- All other sections should always be rendered.
+
+---
+
+# Guardrail Notes
+
+- Treat explicit tool parameters as the default contract for business lookup inputs.
+- Do not encode stable business filters by parsing `:APEX$AI_LAST_USER_PROMPT` or `:APEX$AI_ALL_USER_PROMPTS` when those filters can be modeled as parameters.
+- If both explicit parameters and prompt binds appear in the same retrieve-data tool, the prompt binds must be justified as secondary free-text assistance rather than the primary input path.
+
+---
+
+# Output Template — AI Tool
+```
+    tool {{name}} (
+        name: {{tool.name}}
+        type: retrieveData
+        executionPoint: onDemand
+        description:
+            ```
+            {{description}}
+            ```
+        {{notificationBlock}}
+        settings {
+            {{dataDescriptionBlock}}
+            sqlQuery:
+                ```sql
+                {{settings.sqlQuery}}
+                ```
+        }
+        {{serverSideConditionBlock}}
+        {{securityBlock}}
+
+        {{parameters}}
+
+    )
+```
+
+---
+
+

package/skills/apexlang/templates/shared-components/ai-agents/ai-agents.at-tools.parameters.md

@@ -0,0 +1,171 @@
+---
+templateId: ai-agents.ai-tools.parameters
+componentType: aiAgents
+version: 1.0
+description: Canonical contract and guardrails for AI Tool parameters.
+---
+
+# Purpose
+
+Standardize how AI Tool parameters are documented and rendered inside `tool (...)` blocks.
+
+This file provides the shared parameter contract for AI-agent tool templates such as:
+
+- `ai-agents.ai-tools.retrieve-data-sql.md`
+- `ai-agents.ai-tools.execute-code-client-js.md`
+- `ai-agents.ai-tools.execute-code-server-js.md`
+- `ai-agents.ai-tools.execute-code-server-plsql.md`
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Render parameter definitions only inside an AI Tool block.
+2. Each parameter must use the shape `parameter <STATIC_ID> ( ... )`.
+3. Parameter static IDs should be uppercase with underscores when emitted from examples in this file.
+4. Use `value {}` to define parameter metadata such as `dataType`.
+5. Use `validation {}` for parameter validation attributes such as `required` and `allowedValues`.
+6. Omit optional attributes when they are not needed.
+7. `allowedValues` must be expressed as a JSON-style array literal when present.
+8. Use only supported scalar data types shown in this file unless the AI Tool feature set is expanded elsewhere in this template family.
+9. When a retrieve-data tool has stable business lookup inputs, define them as explicit parameters here instead of expecting SQL to derive them from `:APEX$AI_LAST_USER_PROMPT` or `:APEX$AI_ALL_USER_PROMPTS`.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| parameter.staticId | yes | string | Parameter identifier rendered after `parameter`; prefer uppercase with underscores in examples. |
+| parameter.description | yes | string | Human-readable explanation of the parameter purpose. |
+| value.dataType | optional | enum | Include when the parameter type is known. Supported examples in this file: `boolean`, `clob`, `number`, `varchar2`. |
+| validation.allowedValues | optional | string | JSON-style array string restricting accepted values, for example `"[\"A\",\"B\"]"`. |
+| validation.required | optional | boolean | Defaults to required when omitted; set `false` to make the parameter optional. |
+
+---
+
+# File Structure
+
+Use this file as a parameter snippet library for AI Tool templates.
+
+## Folder Placement
+
+- Canonical path: `templates/shared-components/ai-agents/ai-agents.at-tools.parameters.md`
+
+## Relationship to Other Files
+
+- Imported by AI Tool templates that need reusable parameter examples
+- Referenced from:
+  - `ai-agents.ai-tools.retrieve-data-sql.md`
+  - `ai-agents.ai-tools.execute-code-client-js.md`
+  - `ai-agents.ai-tools.execute-code-server-js.md`
+  - `ai-agents.ai-tools.execute-code-server-plsql.md`
+
+## Expected Usage
+
+1. Load the parent AI Tool template.
+2. Select the parameter patterns needed for the tool being generated.
+3. Replace placeholder names and descriptions with concrete tool-specific values.
+4. Omit example parameter blocks that are not needed by the target tool.
+
+---
+
+# Conditional Rendering Rules
+
+- Render `value {}` only once per parameter.
+- Render `dataType` only when a concrete type is known.
+- Render `validation {}` only when validation metadata is needed.
+- Render `required: false` only for optional parameters, and place it inside `validation {}`.
+- Render `allowedValues` only when the tool input must be constrained to a known set, and place it inside `validation {}` as a JSON-style string.
+- Do not emit empty `value {}` or `validation {}` blocks.
+
+---
+
+# Output Template — Parameter
+
+```
+        parameter {{parameter.staticId}} (
+            description: {{parameter.description}}
+            {{valueBlock}}
+            {{validationBlock}}
+        )
+```
+
+---
+
+# Output Examples
+
+## Boolean Parameter
+
+```
+        parameter BOOLEAN_FLAG (
+            description: Boolean flag example
+            value {
+                dataType: boolean
+            }
+        )
+```
+
+## CLOB Parameter
+
+```
+        parameter LARGE_TEXT (
+            description: Large text example
+            value {
+                dataType: clob
+            }
+        )
+```
+
+## Number Parameter With Allowed Values
+
+```
+        parameter STATUS_CODE (
+            description: Numeric status example
+            value {
+                dataType: number
+            }
+            validation {
+                allowedValues: "[1,2,3]"
+            }
+        )
+```
+
+## Varchar2 Parameter With Allowed Values
+
+```
+        parameter CATEGORY_CODE (
+            description: Text category example
+            value {
+                dataType: varchar2
+            }
+            validation {
+                allowedValues: "[\"AAA\",\"BBB\",\"CCC\"]"
+            }
+        )
+```
+
+## Optional Parameter
+
+```
+        parameter OPTIONAL_NOTE (
+            description: Optional text example
+            value {
+                dataType: varchar2
+            }
+            validation {
+                required: false
+            }
+        )
+```
+
+---
+
+# Guardrails Reminder
+
+- Keep parameter definitions tool-specific when generating final APEXlang.
+- Prefer clear business descriptions over generic placeholder text in real tool artifacts.
+- Do not invent unsupported parameter attributes outside the documented `value {}` and `validation {}` structures.
+- When `allowedValues` is used, emit it only inside `validation {}` and format it as a JSON-style string literal.
+- Prefer explicit parameter blocks for IDs, numbers, codes, names, statuses, types, dates, and other structured filters that the agent can collect or infer before tool execution.
+- Do not treat the raw AI prompt text as the primary parameter channel when the tool contract can express the inputs declaratively.

package/skills/apexlang/templates/shared-components/ai-agents/ai-agents.system-prompt.md

@@ -0,0 +1,43 @@
+---
+templateId: ai-agents.system-prompt
+componentType: aiAgents
+version: 1.0
+
+description: Sample formatting and structure for an AI Agent system prompt
+---
+
+# {{Name of Agent}}
+
+## General
+
+This is a set of general rules for the agent to always follow.
+
+### Run After Any Tool
+At the end of running any tool, always run the following tool(s):
+
+*   {{toolName1}}
+*   {{toolName2}}
+
+
+## {{toolName}}
+
+{{Describe when this tool should run and include only the operational details the model needs in order to use it correctly.}}
+
+### Rules
+
+*   {{A bulleted set of rules for what the tool can and cannot do.}}
+
+## {{toolName}}
+
+{{Describe when this tool should run and include only the operational details the model needs in order to use it correctly.}}
+
+### Rules
+
+*   {{A bulleted set of rules for what the tool can and cannot do.}}
+
+## Authoring Notes
+
+- Use the actual tool execution names from each tool's `name:` property when referring to tools in the system prompt.
+- Keep each tool section focused on routing and validation rules, not implementation prose that already belongs in the tool definition.
+- If a tool has follow-up requirements, state them explicitly in either `## General` or the relevant tool section.
+- Keep the final `genAI.systemPrompt` body at or below 3800 characters. APEX import stores it in a 4000 character column; long narrative examples should be compressed into compact operational routing rules.